Headless / Account

Account menu

Compose an account menu, settings dialog, invitations, and an undoable sign-out.

28 public parts · 2examples

@slices.sh/auth/headlessView as Markdown ↗

Your design. Our behavior.

Explore the tree to see what each part controls. Gates reveal the relevant state; roots outline their scope.

Behavior / inputGateGenericRenderer · not headlessScope

COMPONENT ANATOMYHover · focus · tap

ONE POSSIBLE DESIGNStatic preview

User.Root · Scope

User.RootSays which auth the User parts below read, and whether they may do without it. The parts need no root: left out, they read the nearest auth root's config, or "default", and render nothing without auth. `<User.Root enabled="optional">` is for the one who wants that said in the code.

Sign in Create an account Recover access Profile and contact details Password Connected accounts Active sessions Delete account Switch or create a workspace Workspace settings Members Invitations Join requests Domain access

Installation

Choose what your component needs. Run these commands in an initialized Next.js app.

Before you start

The steps below run in a Next.js app with shadcn set up (it has a components.json). In an existing Next.js app, such as one from create-next-app, set shadcn up first:

npx shadcn@latest init -t next -b base -p nova

Or start fresh: the slices CLI creates the app and sets it up.

npx slices.sh install

Install the service registry

Adds services/index.ts, which import "@/services" loads. A provider setup writes the same file, so skip this if your app has one.

npx add services

Install the headless library

npm

Add the React parts to your app, then compose them with your own elements.

npm install @slices.sh/auth@^0.1.10

Import from @slices.sh/auth/headless.

Install the service

Connect the parts to a provider. Skip this step if this service is already configured in your app.

Provider

Database

Account capabilities

passkeystwo-factororganizationspassword-reset

npx add auth.betterauth --auth-methods google

Adds service configuration and API routes to your app, with the provider dependencies. For a headless composition, add import "@/services" after "use client".

The slices CLI installs the service and provisions its required resources in one command.

Set BETTER_AUTH_URL to your app origin. Memory is for local development; use a persistent database for deployment. Neon and Supabase also require the migration script printed by the installer.

Provider setup notes

BETTER_AUTH_SECRET signs every session and is generated into .env.local while this installs (32 random bytes, base64, nothing leaves the machine). Changing it signs everyone out; in production set the same one on every instance.
The public origin (OAuth callbacks, the passkey domain) is the one each request comes to in development, and the deployment's own on Vercel. Elsewhere, or behind a proxy or a custom domain, set BETTER_AUTH_URL, such as https://acme.com.

Start small

Parts bring the behavior. Use their default elements, or supply your own with render.

example.tsx

"use client"import "@/services"import { UserMenu } from "@slices.sh/auth/headless"export function Example() {  return (    <UserMenu.Root>      <UserMenu.Menu>        <UserMenu.Trigger>My account</UserMenu.Trigger>        <UserMenu.Content>          <UserMenu.SignOut>Sign out</UserMenu.SignOut>        </UserMenu.Content>      </UserMenu.Menu>    </UserMenu.Root>  )}

Requires an authenticated account. Organization controls also require organizations and the appropriate role.

API reference

Every public part used by this experience is listed below. Gates render children without adding an element. Element parts accept native element props and render; function children receive the state declared in their props. Scopes provide context rather than a visual element.

User.SignOutaction · <button>

SignOut is <button type="button"> with { pending } and onSignedOut. For a sign-out with a grace period and Undo, use UserMenu.SignOut.

Props

3 documented props · Native <button> attributes supported

User.SignOut props
Prop	Type	Default
`onSignedOut`	`() => void`	`—`
`children` Content rendered inside this part.	`ReactNode \| ((state: { pending: boolean }) => ReactNode)`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Alternate public imports

User.SignOut from @slices.sh/auth/headless/user
User.SignOut from @slices.sh/auth/headless/passkeys
User.SignOut from @slices.sh/auth/headless/two-factor

Source: @slices.sh/auth/src/headless/user/sign-out.tsx

UserMenu.Rootscope

Menu maps the open state onto a host menu through render={<DropdownMenu />}. Trigger keeps the reference focus returns to when a dialog closes. Content is the popup.

Props

4 documented props

UserMenu.Root props
Prop	Type	Default
`shortcuts`	`boolean`	`false`
`config` The auth config, a slug from the registry (`services/auth/<config>.config.ts`). The nearest root's, else `"default"`, when left out.	`string`	`—`
`enabled` Left out or `true`: required, and missing auth throws. `"optional"`: renders its children and every part inside degrades without auth. `false`: off. A capability name such as `"methods: password"`: requires auth with it.	`Enabled`	`—`
`children` Content rendered inside this part.	`ReactNode`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Alternate public imports

Root from @slices.sh/auth/headless/user-menu

Source: @slices.sh/auth/src/headless/user-menu/root.tsx

UserMenu.Menucontent

Menu maps the open state onto a host menu through render={<DropdownMenu />}. Trigger keeps the reference focus returns to when a dialog closes. Content is the popup.

Required scope

UserMenu.Menu requires Root.

Props

2 documented props

UserMenu.Menu props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Alternate public imports

Menu from @slices.sh/auth/headless/user-menu

Source: @slices.sh/auth/src/headless/user-menu/menu.tsx

UserMenu.Triggeraction · <button>

Menu maps the open state onto a host menu through render={<DropdownMenu />}. Trigger keeps the reference focus returns to when a dialog closes. Content is the popup.

Required scope

UserMenu.Trigger requires Root.

Props

2 documented props · Native <button> attributes supported

UserMenu.Trigger props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Alternate public imports

Trigger from @slices.sh/auth/headless/user-menu

Source: @slices.sh/auth/src/headless/user-menu/trigger.tsx

UserMenu.Contentcontent

Menu maps the open state onto a host menu through render={<DropdownMenu />}. Trigger keeps the reference focus returns to when a dialog closes. Content is the popup.

Required scope

UserMenu.Content requires Root.

Props

2 documented props

UserMenu.Content props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Alternate public imports

Content from @slices.sh/auth/headless/user-menu

Source: @slices.sh/auth/src/headless/user-menu/content.tsx

UserMenu.Manageaction · <button>

Manage section opens the settings dialog on that section (profile by default). SettingsDialog maps it onto render={<Dialog />}, DialogContent is its content, and Settings passes the selected section to a settings panel.

Required scope

UserMenu.Manage requires Root.

Props

3 documented props · Native <button> attributes supported

UserMenu.Manage props
Prop	Type	Default
`section`	`string`	`"profile"`
`children` Content rendered inside this part.	`ReactNode`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Alternate public imports

Manage from @slices.sh/auth/headless/user-menu

Source: @slices.sh/auth/src/headless/user-menu/manage.tsx

UserMenu.SettingsDialogcontent

Required scope

UserMenu.SettingsDialog requires Root.

Props

2 documented props

UserMenu.SettingsDialog props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Alternate public imports

SettingsDialog from @slices.sh/auth/headless/user-menu

Source: @slices.sh/auth/src/headless/user-menu/settings-dialog.tsx

UserMenu.DialogContentcontent

Required scope

UserMenu.DialogContent requires Root.

Props

2 documented props

UserMenu.DialogContent props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Alternate public imports

DialogContent from @slices.sh/auth/headless/user-menu

Source: @slices.sh/auth/src/headless/user-menu/dialog-content.tsx

UserMenu.Settingscontent

Required scope

UserMenu.Settings requires Root.

Props

2 documented props

UserMenu.Settings props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Alternate public imports

Settings from @slices.sh/auth/headless/user-menu

Source: @slices.sh/auth/src/headless/user-menu/settings.tsx

UserMenu.Viewcontent · <div>

View name="main" | "organizations" replaces the menu's items in place; ViewTrigger view switches to one and moves focus once its items are registered.

Required scope

UserMenu.View requires Root.

Props

3 documented props · Native <div> attributes supported

UserMenu.View props
Prop	Type	Default
`name`Required	`"main" \| "organizations"`	`—`
`children` Content rendered inside this part.	`ReactNode`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Alternate public imports

View from @slices.sh/auth/headless/user-menu

Source: @slices.sh/auth/src/headless/user-menu/view.tsx

UserMenu.ViewTriggeraction · <button>

View name="main" | "organizations" replaces the menu's items in place; ViewTrigger view switches to one and moves focus once its items are registered.

Required scope

UserMenu.ViewTrigger requires Root.

Props

3 documented props · Native <button> attributes supported

UserMenu.ViewTrigger props
Prop	Type	Default
`view`Required	`"main" \| "organizations"`	`—`
`children` Content rendered inside this part.	`ReactNode`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Alternate public imports

ViewTrigger from @slices.sh/auth/headless/user-menu

Source: @slices.sh/auth/src/headless/user-menu/view-trigger.tsx

UserMenu.SignOutaction · <button>

SignOut starts a five-second grace period, with { pending, retryAfter }. SignOutNotice is a status region with { pending, seconds }; UndoSignOut cancels before any request. SignOutError is <p role="alert"> with { message }.

Required scope

UserMenu.SignOut requires Root.

Props

2 documented props · Native <button> attributes supported

UserMenu.SignOut props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode \| ((state: { pending: boolean; retryAfter: number }) => ReactNode)`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Alternate public imports

SignOut from @slices.sh/auth/headless/user-menu

Source: @slices.sh/auth/src/headless/user-menu/sign-out.tsx

UserMenu.SignOutNoticecontent · <div>

Required scope

UserMenu.SignOutNotice requires Root.

Props

2 documented props · Native <div> attributes supported

UserMenu.SignOutNotice props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode \| ((state: { pending: boolean; seconds: number }) => ReactNode)`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Alternate public imports

SignOutNotice from @slices.sh/auth/headless/user-menu

Source: @slices.sh/auth/src/headless/user-menu/sign-out-notice.tsx

UserMenu.UndoSignOutaction · <button>

Required scope

UserMenu.UndoSignOut requires Root.

Props

2 documented props · Native <button> attributes supported

UserMenu.UndoSignOut props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Alternate public imports

UndoSignOut from @slices.sh/auth/headless/user-menu

Source: @slices.sh/auth/src/headless/user-menu/undo-sign-out.tsx

UserMenu.SignOutErrorcontent · <p>

Required scope

UserMenu.SignOutError requires Root.

Props

2 documented props · Native <p> attributes supported

UserMenu.SignOutError props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode \| ((state: { message: string }) => ReactNode)`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Alternate public imports

SignOutError from @slices.sh/auth/headless/user-menu

Source: @slices.sh/auth/src/headless/user-menu/sign-out-error.tsx

UserMenu.InvitationsAvailablegate

InvitationsAvailable opens for a verified account where organizations exist. InvitationBadge and InvitationsButton get { count }. InvitationsDialog maps onto a host dialog; inside it InvitationsLoading, InvitationsEmpty, InvitationsError and InvitationsRetry cover the read, Invitations.Item lists them, and AcceptError and DeclineError report the writes.

Capability: organizations

Props

1 documented props

UserMenu.InvitationsAvailable props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Alternate public imports

InvitationsAvailable from @slices.sh/auth/headless/user-menu

Source: @slices.sh/auth/src/headless/user-menu/invitations-available.tsx

UserMenu.InvitationBadgecontent · <span>

Capability: organizations

Props

2 documented props · Native <span> attributes supported

UserMenu.InvitationBadge props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode \| ((state: { count: number }) => ReactNode)`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Alternate public imports

InvitationBadge from @slices.sh/auth/headless/user-menu

Source: @slices.sh/auth/src/headless/user-menu/invitation-badge.tsx

UserMenu.InvitationsButtonaction · <button>

Capability: organizations

Required scope

UserMenu.InvitationsButton requires Root.

Props

2 documented props · Native <button> attributes supported

UserMenu.InvitationsButton props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode \| ((state: { count: number \| null }) => ReactNode)`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Alternate public imports

InvitationsButton from @slices.sh/auth/headless/user-menu

Source: @slices.sh/auth/src/headless/user-menu/invitations-button.tsx

UserMenu.InvitationsDialogcontent

Capability: organizations

Required scope

UserMenu.InvitationsDialog requires Root.

Props

2 documented props

UserMenu.InvitationsDialog props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Alternate public imports

InvitationsDialog from @slices.sh/auth/headless/user-menu

Source: @slices.sh/auth/src/headless/user-menu/invitations-dialog.tsx

UserMenu.InvitationsEmptygate

Capability: organizations

Props

1 documented props

UserMenu.InvitationsEmpty props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Alternate public imports

InvitationsEmpty from @slices.sh/auth/headless/user-menu

Source: @slices.sh/auth/src/headless/user-menu/invitations-empty.tsx

UserMenu.InvitationsLoadinggate

Capability: organizations

Props

1 documented props

UserMenu.InvitationsLoading props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Alternate public imports

InvitationsLoading from @slices.sh/auth/headless/user-menu

Source: @slices.sh/auth/src/headless/user-menu/invitations-loading.tsx

UserMenu.InvitationsErrorcontent · <p>

Capability: organizations

Props

2 documented props · Native <p> attributes supported

UserMenu.InvitationsError props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode \| ((state: { message: string }) => ReactNode)`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Alternate public imports

InvitationsError from @slices.sh/auth/headless/user-menu

Source: @slices.sh/auth/src/headless/user-menu/invitations-error.tsx

UserMenu.InvitationsRetryaction · <button>

Capability: organizations

Props

2 documented props · Native <button> attributes supported

UserMenu.InvitationsRetry props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Alternate public imports

InvitationsRetry from @slices.sh/auth/headless/user-menu

Source: @slices.sh/auth/src/headless/user-menu/invitations-retry.tsx

UserMenu.AcceptErrorcontent · <p>

Capability: organizations

Props

2 documented props · Native <p> attributes supported

UserMenu.AcceptError props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode \| ((state: { message: string }) => ReactNode)`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Alternate public imports

AcceptError from @slices.sh/auth/headless/user-menu

Source: @slices.sh/auth/src/headless/user-menu/accept-error.tsx

UserMenu.DeclineErrorcontent · <p>

Capability: organizations

Props

2 documented props · Native <p> attributes supported

UserMenu.DeclineError props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode \| ((state: { message: string }) => ReactNode)`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Alternate public imports

DeclineError from @slices.sh/auth/headless/user-menu

Source: @slices.sh/auth/src/headless/user-menu/decline-error.tsx

Invitations.Itemcontent · <div>

Item repeats once per invitation with { organizationName }. Accept and Decline act on it with { pending }; their refusals show in UserMenu.AcceptError and DeclineError.

Capability: organizations

Required scope

Invitations.Item renders its own scope.

Props

2 documented props · Native <div> attributes supported

Invitations.Item props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode \| ((state: { organizationName: string }) => ReactNode)`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Alternate public imports

Invitations.Item from @slices.sh/auth/headless/invitations

Source: @slices.sh/auth/src/headless/invitations/item.tsx

Invitations.Acceptaction · <button>

Item repeats once per invitation with { organizationName }. Accept and Decline act on it with { pending }; their refusals show in UserMenu.AcceptError and DeclineError.

Capability: organizations

Required scope

Invitations.Accept must be inside <Invitations.Item>.

Props

2 documented props · Native <button> attributes supported

Invitations.Accept props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode \| ((state: { pending: boolean }) => ReactNode)`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Alternate public imports

Invitations.Accept from @slices.sh/auth/headless/invitations

Source: @slices.sh/auth/src/headless/invitations/accept.tsx

Invitations.Declineaction · <button>

Item repeats once per invitation with { organizationName }. Accept and Decline act on it with { pending }; their refusals show in UserMenu.AcceptError and DeclineError.

Capability: organizations

Required scope

Invitations.Decline must be inside <Invitations.Item>.

Props

2 documented props · Native <button> attributes supported

Invitations.Decline props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode \| ((state: { pending: boolean }) => ReactNode)`	`—`
`render` Replace the default element with your own while retaining the part’s behavior and accessibility.	`ReactElement`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Alternate public imports

Invitations.Decline from @slices.sh/auth/headless/invitations

Source: @slices.sh/auth/src/headless/invitations/decline.tsx

User.Rootscope

Says which auth the User parts below read, and whether they may do without it. The parts need no root: left out, they read the nearest auth root's config, or "default", and render nothing without auth. `<User.Root enabled="optional">` is for the one who wants that said in the code.

Props

3 documented props

User.Root props
Prop	Type	Default
`config` The auth config, a slug from the registry (`services/auth/<config>.config.ts`). The nearest root's, else `"default"`, when left out.	`string`	`—`
`enabled` Left out or `true`: required, and missing auth throws. `"optional"`: renders its children and every part inside degrades without auth. `false`: off. A capability name such as `"methods: password"`: requires auth with it.	`Enabled`	`—`
`children` Content rendered inside this part.	`ReactNode`	`—`

Required props are marked. A dash means no explicit default is declared in this component.

Alternate public imports

User.Root from @slices.sh/auth/headless/user
User.Root from @slices.sh/auth/headless/passkeys
User.Root from @slices.sh/auth/headless/two-factor

Source: @slices.sh/auth/src/headless/user/root.tsx

When something is missing

No service configuration: Install the auth setup below and import "@/services". Required service roots report missing setup; gates do not replace that configuration.
Missing capability or parent scope: Follow each part’s context requirements and the example composition. Capability-aware controls hide when the provider cannot perform their action.

Read the setup guide →