Theme Menu

import { ThemeMenu } from 'ferry-ui'

export default function ThemeMenuHero() {
  // With no `value`, the menu reads and changes the nearest ThemeProvider.
  return <ThemeMenu />
}

This menu changes the theme of this site.

Usage guidelines#

• For the top bar. Put the menu in the actions of a Top Bar, or on a sign-in page.
• No state in your code. With no value, the menu reads and changes the nearest ThemeProvider.
• Not for a settings form. In a form, bind a Toggle Group or a Radio Group to useTheme().

Anatomy#

The menu has one part. The icon of the button shows the current preference: a sun, a moon or a monitor.

import { ThemeMenu } from 'ferry-ui'

<ThemeMenu />

Examples#

Controlled value#

To control the menu, pass value and onValueChange. The menu then does not change the provider. Your code holds the preference.

import * as React from 'react'
import { ThemeMenu, type ThemePreference } from 'ferry-ui'

export default function ThemeMenuControlled() {
  // Your code holds the preference. The menu does not change the ThemeProvider.
  const [preference, setPreference] = React.useState<ThemePreference>('system')

  return (
    <>
      <ThemeMenu value={preference} onValueChange={setPreference} />
      <span className="text-[13px] text-foreground-light">Preference: {preference}</span>
    </>
  )
}

Translated texts#

label sets the heading of the menu and the text of the tooltip. labels sets the names of the three options.

import { ThemeMenu } from 'ferry-ui'

export default function ThemeMenuLabels() {
  return <ThemeMenu label="Thème" labels={{ light: 'Clair', dark: 'Sombre', system: 'Système' }} />
}

Position and tooltip#

align sets the side of the button that the menu aligns to. The default is end. tooltip={false} hides the tooltip.

import { ThemeMenu } from 'ferry-ui'

export default function ThemeMenuAlign() {
  return (
    <>
      <ThemeMenu align="start" tooltip={false} />
      <ThemeMenu align="center" tooltip={false} />
      <ThemeMenu align="end" tooltip={false} />
    </>
  )
}

In a top bar#

className goes to the button. Use it to hide the menu on a phone.

<TopBar
  actions={
    <>
      <TopBarSearch />
      <ThemeMenu className="max-sm:hidden" />
      <TopBarUserMenu name="Maya Chen" />
    </>
  }
/>

Accessibility#

• The accessible name of the button gives the label and the current option, for example "Theme: Dark".
• The tooltip needs a TooltipProvider above the menu. See Tooltip.
• Enter opens the menu. ↑ and ↓ move in the options. Enter selects an option.

API reference#

ThemeMenu accepts only the props of this table. The button has data-slot="theme-menu-trigger", and the panel has data-slot="theme-menu".