- Accordion
- Attachment
- Avatar
- Badge
- Breadcrumb
- Button
- Button Group
- Card
- Checkbox
- Code Block
- Collapsible
- Dialog
- Dropdown Menu
- Empty
- Field
- Hover Card
- Input
- Input Group
- Input OTP
- Item
- Label
- Marker
- Message
- Number Flow
- Pagination
- Popover
- Progress
- Radio Group
- Select
- Slider
- Sonner
- Spinner
- Switch
- Tooltip
- Separator
- Sheet
- Tabs
- Textarea
- Toggle
- Toggle Group
- Trace
Astro serves static HTML first. Dark mode must be set on the <html> element before the first paint, or the page flashes. Use an inline script in <head> plus a client island for the toggle.
Prerequisites
- Astro 5 or newer
- React 19 via
@astrojs/react - Frakment theme block already in
src/styles/global.css
Inline script in head
Add this to src/layouts/Base.astro <head>. It runs before paint and sets the class based on localStorage or the OS preference:
<html lang="en">
<head>
<script is:inline>
(function () {
var stored = localStorage.getItem("theme");
var isDark =
stored === "dark" ||
(stored !== "light" &&
window.matchMedia("(prefers-color-scheme: dark)").matches);
document.documentElement.classList.toggle("dark", isDark);
})();
</script>
</head>
<body>
<slot />
</body>
</html>The is:inline directive keeps the script in the HTML. Without it, Astro bundles the script and it runs after paint, causing a flash.
Create the toggle island
import { MoonIcon, SunIcon } from "lucide-react"
import * as React from "react"
import { Button } from "@/components/ui/button"
export function ModeToggle() {
const [isDark, setIsDark] = React.useState<boolean | null>(null)
React.useEffect(() => {
setIsDark(document.documentElement.classList.contains("dark"))
}, [])
if (isDark === null) {
return <Button variant="ghost" size="icon" aria-label="Toggle theme" />
}
function toggle() {
const next = !isDark
document.documentElement.classList.toggle("dark", next)
localStorage.setItem("theme", next ? "dark" : "light")
setIsDark(next)
}
return (
<Button
variant="ghost"
size="icon"
aria-label="Toggle theme"
onClick={toggle}
>
{isDark ? <SunIcon /> : <MoonIcon />}
</Button>
)
}Mount the island
---
import { ModeToggle } from "@/components/mode-toggle"
---
<header>
<ModeToggle client:load />
</header>client:load hydrates the island immediately. client:idle also works and defers until the browser is idle.
With React islands inside Astro
If your entire app is a React island (client:only="react"), you can use next-themes inside it. The inline script still goes in <head> for the initial class, and next-themes handles the toggle:
import { ThemeProvider } from "next-themes"
export function App() {
return (
<ThemeProvider attribute="class" defaultTheme="system" enableSystem>
{/* routes */}
</ThemeProvider>
)
}Mount with client:only="react" so the provider never runs on the server.
Troubleshooting
The inline script is missing is:inline, or is placed in <body> instead of <head>. Move it to <head> and add is:inline.
The island is missing a client:* directive. Add client:load to <ModeToggle />.
Next
- Theming - token reference
- Vite dark mode - SPA setup
- Astro docs - framework reference