User Menu

API and Development

View SourceOpens in a new tab Submit IssueOpens in a new tab

Import UserMenu, UserMenuStatus from @prepared911/ui/user-menu.

UserMenu

Prop	Type	Description
`name`	`LocalizedMessage \| DisplayValue`	The person's name: initials source, header title, and the visible name with `showName`
`email`	`DisplayValue`	Shown under the name, truncated, full text as `title`
`avatarSrc`	`string`	Photo URL. Initials show without it or when it fails
`initials`	`LocalizedMessage \| DisplayValue`	Avatar text with no photo. Defaults to the first letters of the first two words of `name`
`plan`	`LocalizedMessage`	Plan badge beside the name
`showName`	`boolean`	Draw the name and a chevron from 640px up. Default `false`
`triggerLabel`	`LocalizedMessage \| (status) => LocalizedMessage`	Accessible name of the avatar trigger; required without `trigger`. Include the name, and the status when availability is on
`trigger`	`ReactElement`	A control that opens the menu in place of the avatar button, such as a preferences icon `Button` in a top bar. It keeps its own name; UserMenu adds `aria-haspopup`, `aria-expanded`, the press and arrow-key handlers and focus return. With it, `triggerLabel`, `showName`, `disabled`, `className` and `ref` are not accepted (put them on the control)
`items`	`readonly UserMenuItem[]`	Account destinations
`preferencesLabel`	`LocalizedMessage`	Heading of the preferences group
`appearanceLabels`	`UserMenuAppearanceLabels`	Passing it shows the Theme row
`appearance` / `defaultAppearance` / `onAppearanceChange`	`AppearanceMode`	Controlled value, initial value (default `System`), and the report
`reduceMotionLabel`	`LocalizedMessage`	Passing it shows the Reduce motion row
`reduceMotion` / `defaultReduceMotion` / `onReduceMotionChange`	`boolean`	Controlled value, initial value (default `false`), and the report
`status` / `defaultStatus` / `onStatusChange`	`UserMenuStatus`	Optional. Any of them shows the presence dot and availability rows (default `Available`); with none, nothing renders
`statusLabels`	`UserMenuStatusLabels`	Required with any status prop
`signOutLabel`, `signingOutLabel`	`LocalizedMessage`	Sign out row label, and its label while pending. The row is neutral, not destructive
`onSignOut`	`() => void \| Promise<void>`	A promise keeps the menu open on a busy row until it settles
`open` / `defaultOpen` / `onOpenChange`	`boolean`, `(open, details) => void`	Open state
`side`	`Side`	Default `"block-end"`
`align`	`Align`	Default `"end"`
`disabled`	`boolean`	Inert trigger
`className`	`string`	Appended to the trigger
`ref`	`Ref<HTMLButtonElement>`	The trigger

UserMenuItem

Field	Type	Description
`id`	`string`	Unique among the items
`label`	`LocalizedMessage`	Row label
`icon`	`Glyph`	Leading icon
`shortcut`	`LocalizedMessage`	Optional. Visual hint at the inline end, hidden from assistive technology. Nothing is drawn without it
`disabled`	`boolean`	Inert row
`onSelect`	`() => void`	Called on a press; the menu then closes

Enums

AppearanceMode: Light, Dark, System.
UserMenuStatus: Available (success dot), Busy (error dot), Away (warning dot).

Props

Name	Type	Default	Description
`name`	`UserMenuName`	—	The person's name. It is the avatar's initials source and the header title.
`onSignOut`	`() => void \| Promise<void>`	—	Called when a person presses Sign out. When it returns a promise the row shows a spinner, reads `signingOutLabel`, is `aria-busy`, and ignores further presses until the promise settles; then the menu closes. A rejection is left to the app and still closes the menu.
`signingOutLabel`	`LocalizedMessage`	—	Label of the sign out row while `onSignOut` is pending.
`signOutLabel`	`LocalizedMessage`	—	Label of the sign out row.
`align`	`Align`	`"end"`	Alignment along that edge.
`appearance`	`AppearanceMode`	—	Controlled appearance preference. Pair with `onAppearanceChange`.
`appearanceLabels`	`UserMenuAppearanceLabels`	—	Names of the appearance choices. Passing it shows the Theme row.
`avatarSrc`	`string`	—	Trusted image URL of the person's photo. Without it, or when it fails to load, the initials show.
`className`	`string`	—	Classes appended to the trigger. Put overrides in `@layer chroma.overrides`.
`defaultAppearance`	`AppearanceMode`	`AppearanceMode.System`	Initial appearance preference when uncontrolled.
`defaultOpen`	`boolean`	`false`	Initial open state when uncontrolled.
`defaultReduceMotion`	`boolean`	`false`	Initial reduce motion preference when uncontrolled.
`defaultStatus`	`UserMenuStatus`	`UserMenuStatus.Available`	Initial availability when uncontrolled.
`disabled`	`boolean`	—	Disables the trigger.
`email`	`DisplayValue`	—	The person's email. It is truncated in the header and its full text is the `title`.
`initials`	`UserMenuName`	—	Text shown when there is no photo. Defaults to the first letters of the first two words of `name`.
`items`	`readonly UserMenuItem[]`	—	Account destinations between the header and the preferences.
`onAppearanceChange`	`AppearanceChangeHandler`	—	Called when a person picks an appearance. UserMenu only reports; the app applies it, for example by setting `data-theme` on `<html>`. The menu stays open. May be canceled.
`onOpenChange`	`UserMenuOpenChangeHandler`	—	Called on trigger press (`"trigger-press"`), item press (`"item-press"`), Tab (`"focus-out"`), and Escape or an outside press (`"light-dismiss"`, not cancelable).
`onReduceMotionChange`	`ReduceMotionChangeHandler`	—	Called when a person flips the switch. UserMenu only reports; the app applies it by setting `data-motion="reduced"` on `<html>`. The menu stays open. May be canceled.
`onStatusChange`	`StatusChangeHandler`	—	Called when a person picks an availability. The menu stays open. May be canceled.
`open`	`boolean`	—	Controlled open state. Pair with `onOpenChange`.
`plan`	`LocalizedMessage`	—	Name of the person's plan, drawn as a badge beside the name in the header.
`preferencesLabel`	`LocalizedMessage`	—	Visible heading of the preferences group. Without it the rows sit in the menu with no heading.
`reduceMotion`	`boolean`	—	Controlled reduce motion preference. Pair with `onReduceMotionChange`.
`reduceMotionLabel`	`LocalizedMessage`	—	Label of the Reduce motion switch row. Passing it shows the row.
`ref`	`Ref<HTMLButtonElement>`	—	Ref to the trigger `button`.
`showName`	`boolean`	`false`	Shows the name and a chevron beside the avatar from 640px of viewport width up. Below that only the avatar shows.
`side`	`Side`	`"block-end"`	Preferred edge of the trigger.
`status`	`UserMenuStatus`	—	Controlled availability. Pair with `onStatusChange`.
`statusLabels`	`UserMenuStatusLabels`	—	Names of the availability choices.
`trigger`	`ReactElement<MenuControlChildProps, string \| JSXElementConstructor<any>>`	—	A control that opens the menu in place of the avatar button; see {@link UserMenuCustomTriggerProps}. The control that opens the menu, usually a `Button`. UserMenu adds `aria-haspopup="menu"`, `aria-expanded`, the press and arrow-key handlers and, on close, returns focus to it; the control's own handlers run first and its `ref` is kept. Name it with its own `label`, and set `disabled`, `className` and `ref` on it, not on UserMenu.
`triggerLabel`	`((LocalizedMessage \| ((status: UserMenuStatus) => LocalizedMessage)) & (LocalizedMessage \| ((status: UserMenuStatus \| undefined) => LocalizedMessage))) \| undefined`	—	Name of the avatar trigger. Required with it; see {@link UserMenuAvatarTriggerProps}. Accessible name of the avatar trigger, such as "Dana Levi, account menu". It includes the person's name and, when availability is shown, the current status. A function receives the current status so the name follows an uncontrolled choice.

Storybook

Interactive examples and edge cases for this component are in Storybook.

DefaultOpens in a new tab

User Menu / Usage

User Menu / Accessibility

On this page

User Menu

API and Development

View SourceOpens in a new tab Submit IssueOpens in a new tab

Import UserMenu, UserMenuStatus from @prepared911/ui/user-menu.

UserMenu

Prop	Type	Description
`name`	`LocalizedMessage \| DisplayValue`	The person's name: initials source, header title, and the visible name with `showName`
`email`	`DisplayValue`	Shown under the name, truncated, full text as `title`
`avatarSrc`	`string`	Photo URL. Initials show without it or when it fails
`initials`	`LocalizedMessage \| DisplayValue`	Avatar text with no photo. Defaults to the first letters of the first two words of `name`
`plan`	`LocalizedMessage`	Plan badge beside the name
`showName`	`boolean`	Draw the name and a chevron from 640px up. Default `false`
`triggerLabel`	`LocalizedMessage \| (status) => LocalizedMessage`	Accessible name of the avatar trigger; required without `trigger`. Include the name, and the status when availability is on
`trigger`	`ReactElement`	A control that opens the menu in place of the avatar button, such as a preferences icon `Button` in a top bar. It keeps its own name; UserMenu adds `aria-haspopup`, `aria-expanded`, the press and arrow-key handlers and focus return. With it, `triggerLabel`, `showName`, `disabled`, `className` and `ref` are not accepted (put them on the control)
`items`	`readonly UserMenuItem[]`	Account destinations
`preferencesLabel`	`LocalizedMessage`	Heading of the preferences group
`appearanceLabels`	`UserMenuAppearanceLabels`	Passing it shows the Theme row
`appearance` / `defaultAppearance` / `onAppearanceChange`	`AppearanceMode`	Controlled value, initial value (default `System`), and the report
`reduceMotionLabel`	`LocalizedMessage`	Passing it shows the Reduce motion row
`reduceMotion` / `defaultReduceMotion` / `onReduceMotionChange`	`boolean`	Controlled value, initial value (default `false`), and the report
`status` / `defaultStatus` / `onStatusChange`	`UserMenuStatus`	Optional. Any of them shows the presence dot and availability rows (default `Available`); with none, nothing renders
`statusLabels`	`UserMenuStatusLabels`	Required with any status prop
`signOutLabel`, `signingOutLabel`	`LocalizedMessage`	Sign out row label, and its label while pending. The row is neutral, not destructive
`onSignOut`	`() => void \| Promise<void>`	A promise keeps the menu open on a busy row until it settles
`open` / `defaultOpen` / `onOpenChange`	`boolean`, `(open, details) => void`	Open state
`side`	`Side`	Default `"block-end"`
`align`	`Align`	Default `"end"`
`disabled`	`boolean`	Inert trigger
`className`	`string`	Appended to the trigger
`ref`	`Ref<HTMLButtonElement>`	The trigger

UserMenuItem

Field	Type	Description
`id`	`string`	Unique among the items
`label`	`LocalizedMessage`	Row label
`icon`	`Glyph`	Leading icon
`shortcut`	`LocalizedMessage`	Optional. Visual hint at the inline end, hidden from assistive technology. Nothing is drawn without it
`disabled`	`boolean`	Inert row
`onSelect`	`() => void`	Called on a press; the menu then closes

Enums

AppearanceMode: Light, Dark, System.
UserMenuStatus: Available (success dot), Busy (error dot), Away (warning dot).

Props

Name	Type	Default	Description
`name`	`UserMenuName`	—	The person's name. It is the avatar's initials source and the header title.
`onSignOut`	`() => void \| Promise<void>`	—	Called when a person presses Sign out. When it returns a promise the row shows a spinner, reads `signingOutLabel`, is `aria-busy`, and ignores further presses until the promise settles; then the menu closes. A rejection is left to the app and still closes the menu.
`signingOutLabel`	`LocalizedMessage`	—	Label of the sign out row while `onSignOut` is pending.
`signOutLabel`	`LocalizedMessage`	—	Label of the sign out row.
`align`	`Align`	`"end"`	Alignment along that edge.
`appearance`	`AppearanceMode`	—	Controlled appearance preference. Pair with `onAppearanceChange`.
`appearanceLabels`	`UserMenuAppearanceLabels`	—	Names of the appearance choices. Passing it shows the Theme row.
`avatarSrc`	`string`	—	Trusted image URL of the person's photo. Without it, or when it fails to load, the initials show.
`className`	`string`	—	Classes appended to the trigger. Put overrides in `@layer chroma.overrides`.
`defaultAppearance`	`AppearanceMode`	`AppearanceMode.System`	Initial appearance preference when uncontrolled.
`defaultOpen`	`boolean`	`false`	Initial open state when uncontrolled.
`defaultReduceMotion`	`boolean`	`false`	Initial reduce motion preference when uncontrolled.
`defaultStatus`	`UserMenuStatus`	`UserMenuStatus.Available`	Initial availability when uncontrolled.
`disabled`	`boolean`	—	Disables the trigger.
`email`	`DisplayValue`	—	The person's email. It is truncated in the header and its full text is the `title`.
`initials`	`UserMenuName`	—	Text shown when there is no photo. Defaults to the first letters of the first two words of `name`.
`items`	`readonly UserMenuItem[]`	—	Account destinations between the header and the preferences.
`onAppearanceChange`	`AppearanceChangeHandler`	—	Called when a person picks an appearance. UserMenu only reports; the app applies it, for example by setting `data-theme` on `<html>`. The menu stays open. May be canceled.
`onOpenChange`	`UserMenuOpenChangeHandler`	—	Called on trigger press (`"trigger-press"`), item press (`"item-press"`), Tab (`"focus-out"`), and Escape or an outside press (`"light-dismiss"`, not cancelable).
`onReduceMotionChange`	`ReduceMotionChangeHandler`	—	Called when a person flips the switch. UserMenu only reports; the app applies it by setting `data-motion="reduced"` on `<html>`. The menu stays open. May be canceled.
`onStatusChange`	`StatusChangeHandler`	—	Called when a person picks an availability. The menu stays open. May be canceled.
`open`	`boolean`	—	Controlled open state. Pair with `onOpenChange`.
`plan`	`LocalizedMessage`	—	Name of the person's plan, drawn as a badge beside the name in the header.
`preferencesLabel`	`LocalizedMessage`	—	Visible heading of the preferences group. Without it the rows sit in the menu with no heading.
`reduceMotion`	`boolean`	—	Controlled reduce motion preference. Pair with `onReduceMotionChange`.
`reduceMotionLabel`	`LocalizedMessage`	—	Label of the Reduce motion switch row. Passing it shows the row.
`ref`	`Ref<HTMLButtonElement>`	—	Ref to the trigger `button`.
`showName`	`boolean`	`false`	Shows the name and a chevron beside the avatar from 640px of viewport width up. Below that only the avatar shows.
`side`	`Side`	`"block-end"`	Preferred edge of the trigger.
`status`	`UserMenuStatus`	—	Controlled availability. Pair with `onStatusChange`.
`statusLabels`	`UserMenuStatusLabels`	—	Names of the availability choices.
`trigger`	`ReactElement<MenuControlChildProps, string \| JSXElementConstructor<any>>`	—	A control that opens the menu in place of the avatar button; see {@link UserMenuCustomTriggerProps}. The control that opens the menu, usually a `Button`. UserMenu adds `aria-haspopup="menu"`, `aria-expanded`, the press and arrow-key handlers and, on close, returns focus to it; the control's own handlers run first and its `ref` is kept. Name it with its own `label`, and set `disabled`, `className` and `ref` on it, not on UserMenu.
`triggerLabel`	`((LocalizedMessage \| ((status: UserMenuStatus) => LocalizedMessage)) & (LocalizedMessage \| ((status: UserMenuStatus \| undefined) => LocalizedMessage))) \| undefined`	—	Name of the avatar trigger. Required with it; see {@link UserMenuAvatarTriggerProps}. Accessible name of the avatar trigger, such as "Dana Levi, account menu". It includes the person's name and, when availability is shown, the current status. A function receives the current status so the name follows an uncontrolled choice.

Storybook

Interactive examples and edge cases for this component are in Storybook.

DefaultOpens in a new tab

User Menu / Usage

User Menu / Accessibility

On this page