Back to Rendering Performance
Prevent Hydration Mismatch Without Flickering
renderingssrhydrationlocalStorageflicker
Install this skill
npx skills add vercel-labs/agent-skillsWorks across Claude Code, Cursor, Codex, Copilot & Antigravity
Hydration mismatches occur when server-rendered HTML fails to match the initial client-side render, often due to accessing browser-specific APIs like localStorage before the component mounts. Simply relying on React's useEffect to apply user preferences leads to a noticeable visual flash as the component re-renders with the correct state. This skill resolves these issues by inserting a synchronous, blocking script directly after the container element. By executing this script before the browser finishes painting, you update the DOM state immediately. This method bypasses the standard React lifecycle for these initial style updates, ensuring the user sees the intended theme or preference without any layout shift or inconsistencies during the hydration phase. It creates a stable, performant experience for any UI element dependent on persisted browser storage.
When to Use This Skill
- •Applying saved dark or light mode preferences on page load
- •Restoring authenticated UI states based on browser-stored tokens
- •Setting font size preferences or accessibility overrides immediately
- •Localizing display settings stored in persistent browser storage
- •Initializing complex dashboard layouts based on cached user configurations
How to Invoke This Skill
Example prompts that trigger this skill in Claude Code, Cursor, or Antigravity:
- “Stop dark mode flash on page load
- “Fix hydration mismatch for user theme
- “How to apply localStorage state before React renders
- “Prevent visual flicker during hydration
- “Synchronous DOM updates for server-side rendered components
What this skill does
- •Injects synchronous scripts to modify DOM nodes before React hydration
- •Bypasses flicker-inducing layout shifts caused by delayed useEffect updates
- •Prevents server-side errors caused by accessing undefined client APIs
- •Standardizes CSS class or attribute application during the first paint
- •Maintains zero-dependency, vanilla JavaScript compatibility
When not to use it
- ✕When the state data originates from a server-side API or database
- ✕When simple CSS variables can handle the logic via media queries
- ✕When the UI component must remain strictly declarative without raw DOM manipulation
Example workflow
- Identify the UI element that requires a stored user preference
- Remove existing useEffect hooks responsible for updating that state
- Wrap the target component in a parent div with a unique ID
- Append a dangerouslySetInnerHTML script block immediately following the element
- Write the script to fetch the storage value and modify the element class directly
- Verify the page renders the correct state on the first paint
Prerequisites
- –React or Next.js framework environment
- –Basic understanding of the DOM rendering lifecycle
Pitfalls & limitations
- !Requires manual maintenance of DOM IDs to target elements
- !Bypassing React state makes the UI partially non-declarative
- !Script injection must be placed precisely to ensure execution timing
FAQ
Why not just use useEffect?
useEffect runs after the browser paints the initial HTML, which causes the user to see the default state before it switches to the stored state.
Does this cause security risks?
Since the script is authored by you and does not accept external input, it remains safe, though you should always sanitize any values read from storage before injecting them into the DOM.
Will this break React's virtual DOM sync?
No, because React treats the container element as the source of truth; modifying child classes or styles synchronously avoids conflict if handled carefully.
Is this approach specific to Next.js?
While common in Next.js, this pattern applies to any server-rendered React application that experiences hydration mismatches.
How it compares
While manual useEffect methods cause visual flickering, this approach uses blocking scripts to manipulate the DOM during the paint cycle, ensuring the UI is correct on the first frame without extra framework overhead.
📄 Full skill instructions — original source: vercel-labs/agent-skills
## Prevent Hydration Mismatch Without Flickering
When rendering content that depends on client-side storage (localStorage, cookies), avoid both SSR breakage and post-hydration flickering by injecting a synchronous script that updates the DOM before React hydrates.
**Incorrect (breaks SSR):**
Server-side rendering will fail because
**Incorrect (visual flickering):**
Component first renders with default value (
**Correct (no flicker, no hydration mismatch):**
The inline script executes synchronously before showing the element, ensuring the DOM already has the correct value. No flickering, no hydration mismatch.
This pattern is especially useful for theme toggles, user preferences, authentication states, and any client-only data that should render immediately without flashing default values.
When rendering content that depends on client-side storage (localStorage, cookies), avoid both SSR breakage and post-hydration flickering by injecting a synchronous script that updates the DOM before React hydrates.
**Incorrect (breaks SSR):**
function ThemeWrapper({ children }: { children: ReactNode }) {
// localStorage is not available on server - throws error
const theme = localStorage.getItem('theme') || 'light'
return (
<div className={theme}>
{children}
</div>
)
}Server-side rendering will fail because
localStorage is undefined.**Incorrect (visual flickering):**
function ThemeWrapper({ children }: { children: ReactNode }) {
const [theme, setTheme] = useState('light')
useEffect(() => {
// Runs after hydration - causes visible flash
const stored = localStorage.getItem('theme')
if (stored) {
setTheme(stored)
}
}, [])
return (
<div className={theme}>
{children}
</div>
)
}Component first renders with default value (
light), then updates after hydration, causing a visible flash of incorrect content.**Correct (no flicker, no hydration mismatch):**
function ThemeWrapper({ children }: { children: ReactNode }) {
return (
<>
<div id="theme-wrapper">
{children}
</div>
<script
dangerouslySetInnerHTML={{
__html:
(function() {
try {
var theme = localStorage.getItem('theme') || 'light';
var el = document.getElementById('theme-wrapper');
if (el) el.className = theme;
} catch (e) {}
})();
}}
/>
</>
)
}The inline script executes synchronously before showing the element, ensuring the DOM already has the correct value. No flickering, no hydration mismatch.
This pattern is especially useful for theme toggles, user preferences, authentication states, and any client-only data that should render immediately without flashing default values.
How to Use This Skill Unit
Option A: Project-Specific (Recommended)
- Click "Download" above
- In your project, create the directory:
.agent/skills/rendering-hydration-no-flicker/ - Save the file as
SKILL.md - The agent will automatically discover the skill based on its description.
Option B: Global Installation (All Agents)
Save the file to these locations to make it available across all projects:
- Claude Code:
~/.claude/skills/vercel-labs/agent-skills/rendering-hydration-no-flicker/SKILL.md - Cursor:
~/.cursor/skills/vercel-labs/agent-skills/rendering-hydration-no-flicker/SKILL.md - Antigravity:
~/.gemini/antigravity/skills/vercel-labs/agent-skills/rendering-hydration-no-flicker/SKILL.md
🚀 Install with CLI:npx skills add vercel-labs/agent-skills
Recommended Rules
View more rules →Advanced AWS Integration (EventBridge, Step Functions)
AWSIntegrationServerless
You are an expert in advanced AWS integration services and patterns. Key Principles: - Choreography (Events) vs Orchestration (Workflows) - Decouplin...
Antigravity Workflow Fundamentals
WorkflowsAutomationBest Practices
You are an expert in creating Antigravity Workflows. Key Principles: - Workflows are step-by-step recipes for complex tasks - Must be in .agent/workf...
Git Feature Branch Workflow
WorkflowsGitVersion Control
Create a workflow to start new feature branches synchronized with main. Workflow File: .agent/workflows/start_feature.md ```markdown --- description...
Recommended Workflows
View more workflows →Fix Next.js Hydration Errors
Next.jsDebuggingHydration
--- description: Systematically debug and fix 'Text content does not match server-rendered HTML' errors --- 1. **Check for Invalid HTML Nesting**: ...
Automatic commit message generator
GitAIAutomation
--- description: Automatic commit message generator and fast AI-powered commit for all current changes --- // turbo-all This workflow automatically ...
Nuke & Reinstall
npmTroubleshootingDependencies
--- description: The nuclear option for when dependencies are completely broken --- 1. **Remove node_modules**: - Delete the existing `node_module...
