HelixOverviewComponentsMapsGraphIntroductionInstallationDeriving a themeSandboxTheme builderVisual testingCortexDocsEngramActiveTraceActiveRecallActiveServicesInsightsGet in touchSource on GitHub
Loading the reference
Theme ToggleView sourceEdit in SandboxView MarkdownCopy MarkdownOpen in ClaudeOpen in CursorA button that switches the page between light and dark, with the new mode spreading from the button.Also called Dark mode toggle, Color mode switch, Light and dark switch, and Theme switcher.ExperimentalSince 0.241.0ActionsImportimport'@fusion.dev/helix/theme-toggle'import'@fusion.dev/helix-headless/theme-toggle'Preview
API referenceRoothelix-theme-toggleA button that switches the page between light and dark, with the new mode spreading from the button.
PropTypeDescriptionfallbackLabelstringDefault"Dark mode"The name the element gives itself where label is empty.labelstringDefault""The button's name, which stays the same whichever way it stands.transition"circle"|"fade"|"none"|"wipe"How the page moves to the other mode: circle from the button, wipe
across from the inline start, fade, or none.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The button's text, where it shows more than its icon. Defaults to nothing, the icon alone, named by label.iconReplaces the icon, which is the moon while the page is light and the sun while it is dark.
EventTypeDescriptionchangeEventFired once a press has switched the page's color mode.
PartDescriptionbuttonThe toggle button, with aria-pressed while the page is dark.iconThe icon inside the button.
CSS PropertyDescription--theme-toggle-background-colorThe button's fill. Defaults to the floating overlay surface.--theme-toggle-origin-xWhere a circle spreads from, across the viewport, while it runs. Written on the document element.--theme-toggle-origin-yWhere a circle spreads from, down the viewport, while it runs. Written on the document element.--theme-toggle-radiusHow far a circle reaches, to the viewport's furthest corner, while it runs. Written on the document element.
Custom stateDescriptiondarkThe page is in dark mode.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Roothelix-headless-theme-toggleA button that switches the page between light and dark, with the new mode spreading from the button.
PropTypeDescriptionfallbackLabelstringDefault"Dark mode"The name the element gives itself where label is empty.labelstringDefault""The button's name, which stays the same whichever way it stands.transition"circle"|"fade"|"none"|"wipe"How the page moves to the other mode: circle from the button, wipe
across from the inline start, fade, or none.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The button's text, where it shows more than its icon. Defaults to nothing, the icon alone, named by label.iconReplaces the icon, which is the moon while the page is light and the sun while it is dark.
EventTypeDescriptionchangeEventFired once a press has switched the page's color mode.
PartDescriptionbuttonThe toggle button, with aria-pressed while the page is dark.iconThe icon inside the button.
CSS PropertyDescription--theme-toggle-origin-xWhere a circle spreads from, across the viewport, while it runs. Written on the document element.--theme-toggle-origin-yWhere a circle spreads from, down the viewport, while it runs. Written on the document element.--theme-toggle-radiusHow far a circle reaches, to the viewport's furthest corner, while it runs. Written on the document element.
Custom stateDescriptiondarkThe page is in dark mode.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Examples
NameDescriptionPreviewThe page's light and dark switch, as an icon alone and with words beside it. A press spreads the other mode from the button.PreviewThe page's light and dark switch, as an icon alone and with words beside it. A press spreads the other mode from the button.TransitionsThe three ways a press can move the page to the other mode: spreading in a circle from the button, wiping across, and fading.