Headless / Organizations

Switch or create a workspace

Search accessible organizations and switch the active workspace.

29 public parts · 3examples

@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 Account menu Password Connected accounts Active sessions Delete account 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 --organizations

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 { User, Organization } from "@slices.sh/auth/headless"export function Example() {  return (    <User.Root>      <Organization.Switcher.Options>        <Organization.Switcher.Input aria-label="Find a workspace" />        <Organization.Switcher.List>          <Organization.Switcher.Item />        </Organization.Switcher.List>        <Organization.Switcher.Empty>          No matches.        </Organization.Switcher.Empty>      </Organization.Switcher.Options>    </User.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.

Organization.Rolecontent

For the organization in scope. Name is text. Logo is <img alt=""> and nothing without a logo. Role gets { role }, the person's role in it. Manage is the host's link to the active organization's settings.

Required scope

Organization.Role requires Organization.Item or Organization.Active.

Props

2 documented props

Organization.Role props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode \| ((state: { role: MemberRole \| 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

Organization.Role from @slices.sh/auth/headless/organization

Source: @slices.sh/auth/src/headless/organization/role.tsx

Organization.Managecontent · <a>

The host owns where settings for the currently active organization live.

Props

2 documented props · Native <a> attributes supported

Organization.Manage 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

Organization.Manage from @slices.sh/auth/headless/organization

Source: @slices.sh/auth/src/headless/organization/manage.tsx

Organization.Itemaction · <button>

Item is a <button> repeated once per organization with { active, pending }; clicking makes it active. Personal switches to the personal account. Active renders its children with the active organization in scope, and nothing on the personal account; None is its mirror, once the answer is in. Switcher holds the searchable list: Switcher.Surface maps onto a Popover or a Sheet, Switcher.Options, Input, List, Item, Empty and Error search and list, and Switcher.Shortcuts binds keys to switch.

Capability: organizations

Props

2 documented props · Native <button> attributes supported

Organization.Item props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode \| ((state: { active: boolean; 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

Organization.Item from @slices.sh/auth/headless/organization

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

Organization.Personalaction · <button>

Capability: organizations

Props

2 documented props · Native <button> attributes supported

Organization.Personal props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode \| ((state: { active: 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

Organization.Personal from @slices.sh/auth/headless/organization

Source: @slices.sh/auth/src/headless/organization/personal.tsx

Organization.Activegate

Capability: organizations

Props

1 documented props

Organization.Active 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

Organization.Active from @slices.sh/auth/headless/organization

Source: @slices.sh/auth/src/headless/organization/active.tsx

Organization.Nonegate

Capability: organizations

Props

1 documented props

Organization.None 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

Organization.None from @slices.sh/auth/headless/organization

Source: @slices.sh/auth/src/headless/organization/none.tsx

Organization.Namecontent

Required scope

Organization.Name must be inside <Organization.Item> or <Organization.Active>.

Props

2 documented props

Organization.Name 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

Organization.Name from @slices.sh/auth/headless/organization

Source: @slices.sh/auth/src/headless/organization/name.tsx

Organization.Logocontent · <img>

Required scope

Organization.Logo must be inside <Organization.Item> or <Organization.Active>.

Props

2 documented props · Native <img> attributes supported

Organization.Logo 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

Organization.Logo from @slices.sh/auth/headless/organization

Source: @slices.sh/auth/src/headless/organization/logo.tsx

Organization.Loadinggate

Loading covers the first load only. Empty opens when the person belongs to none. Error gets { code, message }.

Props

1 documented props

Organization.Loading 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

Organization.Loading from @slices.sh/auth/headless/organization

Source: @slices.sh/auth/src/headless/organization/loading.tsx

Organization.Emptygate

Loading covers the first load only. Empty opens when the person belongs to none. Error gets { code, message }.

Props

1 documented props

Organization.Empty 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

Organization.Empty from @slices.sh/auth/headless/organization

Source: @slices.sh/auth/src/headless/organization/empty.tsx

Organization.Errorgate

Loading covers the first load only. Empty opens when the person belongs to none. Error gets { code, message }.

Props

1 documented props

Organization.Error props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode \| ((state: { code: AuthErrorCode; message: string }) => ReactNode)`	`—`

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

Alternate public imports

Organization.Error from @slices.sh/auth/headless/organization

Source: @slices.sh/auth/src/headless/organization/error.tsx

Organization.Switcher.Shortcutsscope

Organization.Switcher.Shortcuts provides state to the parts inside it.

Props

2 documented props

Organization.Switcher.Shortcuts props
Prop	Type	Default
`enabled`	`boolean`	`false`
`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

Organization.Switcher.Shortcuts from @slices.sh/auth/headless/organization

Source: @slices.sh/auth/src/headless/organization/switch-shortcuts.tsx

Organization.Switcher.Surfacecontent

Organization.Switcher.Surface renders content from its current scope.

Props

2 documented props

Organization.Switcher.Surface 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

Organization.Switcher.Surface from @slices.sh/auth/headless/organization

Source: @slices.sh/auth/src/headless/organization/switcher-surface.tsx

Organization.Switcher.Optionsscope

Organization.Switcher.Options provides state to the parts inside it.

Props

1 documented props

Organization.Switcher.Options 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

Organization.Switcher.Options from @slices.sh/auth/headless/organization

Source: @slices.sh/auth/src/headless/organization/search-root.tsx

Organization.Switcher.Inputinput · <input>

Organization.Switcher.Input renders a input element.

Props

2 documented props · Native <input> attributes supported

Organization.Switcher.Input 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

Organization.Switcher.Input from @slices.sh/auth/headless/organization

Source: @slices.sh/auth/src/headless/organization/search-input.tsx

Organization.Switcher.Listcontent · <div>

Organization.Switcher.List renders a div element.

Props

2 documented props · Native <div> attributes supported

Organization.Switcher.List 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

Organization.Switcher.List from @slices.sh/auth/headless/organization

Source: @slices.sh/auth/src/headless/organization/search-list.tsx

Organization.Switcher.Itemcontent · <div>

Organization.Switcher.Item renders a div element.

Required scope

Organization.Switcher.Item must be inside <Organization.Switcher.Options>.

Props

2 documented props · Native <div> attributes supported

Organization.Switcher.Item props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode \| ((state: { active: boolean; 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

Organization.Switcher.Item from @slices.sh/auth/headless/organization

Source: @slices.sh/auth/src/headless/organization/search-item.tsx

Organization.Switcher.Emptygate

Organization.Switcher.Empty conditionally renders its children.

Required scope

Organization.Switcher.Empty must be inside <Organization.Switcher.Options>.

Props

1 documented props

Organization.Switcher.Empty 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

Organization.Switcher.Empty from @slices.sh/auth/headless/organization

Source: @slices.sh/auth/src/headless/organization/search-empty.tsx

Organization.Switcher.Errorgate

Organization.Switcher.Error conditionally renders its children.

Props

1 documented props

Organization.Switcher.Error props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode \| ((state: { code: AuthErrorCode; message: string }) => ReactNode)`	`—`

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

Alternate public imports

Organization.Switcher.Error from @slices.sh/auth/headless/organization

Source: @slices.sh/auth/src/headless/organization/search-error.tsx

Organization.Create.Dialogcontent

Organization.Create.Dialog renders content from its current scope.

Props

2 documented props

Organization.Create.Dialog 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

Organization.Create.Dialog from @slices.sh/auth/headless/organization

Source: @slices.sh/auth/src/headless/organization/create-dialog.tsx

Organization.Create.Triggeraction · <button>

Organization.Create.Trigger renders a button element.

Props

2 documented props · Native <button> attributes supported

Organization.Create.Trigger props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode \| ((state: { query: 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

Organization.Create.Trigger from @slices.sh/auth/headless/organization

Source: @slices.sh/auth/src/headless/organization/create-trigger.tsx

Organization.Create.Formaction · <form>

Organization.Create.Form renders a form element.

Props

2 documented props · Native <form> attributes supported

Organization.Create.Form 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

Organization.Create.Form from @slices.sh/auth/headless/organization

Source: @slices.sh/auth/src/headless/organization/create-form.tsx

Organization.Create.Labelcontent · <label>

Organization.Create.Label renders a label element.

Required scope

Organization.Create.Label must be inside <Organization.Create.Form>.

Props

2 documented props · Native <label> attributes supported

Organization.Create.Label 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

Organization.Create.Label from @slices.sh/auth/headless/organization

Source: @slices.sh/auth/src/headless/organization/create-label.tsx

Organization.Create.Nameinput · <input>

Organization.Create.Name renders a input element.

Required scope

Organization.Create.Name must be inside <Organization.Create.Form>.

Props

2 documented props · Native <input> attributes supported

Organization.Create.Name props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode \| ((state: { invalid: 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

Organization.Create.Name from @slices.sh/auth/headless/organization

Source: @slices.sh/auth/src/headless/organization/create-name.tsx

Organization.Create.Submitaction · <button>

Organization.Create.Submit renders a button element.

Required scope

Organization.Create.Submit must be inside <Organization.Create.Form>.

Props

2 documented props · Native <button> attributes supported

Organization.Create.Submit 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

Organization.Create.Submit from @slices.sh/auth/headless/organization

Source: @slices.sh/auth/src/headless/organization/create-submit.tsx

Organization.Create.Errorcontent · <div>

Organization.Create.Error renders a div element.

Props

2 documented props · Native <div> attributes supported

Organization.Create.Error props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode \| ((state: { code: AuthErrorCode; 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

Organization.Create.Error from @slices.sh/auth/headless/organization

Source: @slices.sh/auth/src/headless/organization/create-error.tsx

Principals.Knowngate

Known renders once the session and the organizations are known; nothing for a visitor or a backend without sessions.

Props

1 documented props

Principals.Known 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

Principals.Known from @slices.sh/auth/headless/principals

Source: @slices.sh/auth/src/headless/principals/known.tsx

Principals.PersonalOptioncontent · <option>

PersonalOption is an <option> for the viewer themselves, its value locked to their principal, with { name }. OrganizationOption repeats an <option> per organization the viewer belongs to, its name as default content, and renders nothing without organizations.

Capability: organizations

Props

2 documented props · Native <option> attributes supported

Principals.PersonalOption props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode \| ((state: { name: string \| 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

Principals.PersonalOption from @slices.sh/auth/headless/principals

Source: @slices.sh/auth/src/headless/principals/personal-option.tsx

Principals.OrganizationOptioncontent · <option>

Capability: organizations

Props

2 documented props · Native <option> attributes supported

Principals.OrganizationOption props
Prop	Type	Default
`children` Content rendered inside this part.	`ReactNode \| ((state: { name: 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

Principals.OrganizationOption from @slices.sh/auth/headless/principals

Source: @slices.sh/auth/src/headless/principals/organization-option.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

User.SignedIngate

SignedIn and SignedOut open once the session has answered, so nobody flashes signed out. Loading covers the first load only. SessionExpired opens when the session on screen has run out while its name and picture are still shown. ReadError is <p role="alert"> with { message } when the session could not be read, and Retry reads it again.

Props

1 documented props

User.SignedIn 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

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

Source: @slices.sh/auth/src/headless/user/signed-in.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 →