# Profile

A surface you navigate: a column of pages beside the page each one opens, as tabs. When narrow, the nav becomes a select on the page title, then a sheet on a phone. Inside a `Dialog` it adds the close control.

## Use for

- a user or organization profile with several pages
- a settings surface with side navigation
- a tabbed page layout that collapses on small screens

## Practices

- Do: Render a `Profile.Title`. It names the nav, and stays visually hidden.
- Do: Give each `Profile.NavItem` a `value` that matches a `Profile.ContentPanel`, and pass the selected page name as `pageTitle`.
- Do: Pass a string as a `Profile.NavItem` child, so it names the option when the nav is a select.
- Don't: Render a `Panel.Title` inside `Profile.ContentPanel` and expect it to show. `Profile.Content` renders the page title.

## API reference

### Profile.Root

Holds the selected page and the nav layout. Renders a `div`, or the `render` element.

Slot: `cl-profile`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` |  | The selected page. |
| `onValueChange` | `(value: string) => void` |  | Called with the page the user picks. |
| `orientation` | `TabsProps['orientation']` | `'vertical'` | Tab arrow-key direction. |
| `activationMode` | `TabsProps['activationMode']` |  | Whether focusing a tab selects it. The sheet nav always uses `manual`. |
| `renderBranding` | `boolean` | `true` | Shows Clerk branding in the wide layout. |
| `elevation` | `ProfileElevation` | `'card'` | `card` draws a card. `flush` sits inline in the page; inside a `Dialog` it stays `card`. |

### Profile.Title

A visually hidden heading at the current level that names the profile and its nav.

Slot: `cl-profile-title`

### Profile.Nav

A `nav` of `Profile.NavItem`s or `Profile.NavGroup`s. Renders as a tablist, the options of the page title select, or a tablist in a sheet.

Slot: `cl-profile-nav`

### Profile.NavGroup

A labelled run of nav items. As tabs the label describes each item; as options it names the group.

Slot: `cl-profile-nav-group`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `React.ReactNode` |  | The group name, shown above its items. |

### Profile.NavItem

One page in the nav, as a tab or an option.

Slot: `cl-profile-nav-item`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` |  | The page it opens. |
| `icon` | `React.ReactNode` |  | A leading icon, hidden from assistive tech. |
| `badge` | `React.ReactNode` |  | A trailing `Badge`. Badges in it default to `neutral`. |
| `disabled` | `boolean` |  | Disables the item. |

### Profile.Content

The scrolling page area. Renders the page title, then its children.

Slot: `cl-profile-content`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `pageTitle` | `React.ReactNode` |  | The selected page name, shown as the page title. |

### Profile.ContentPanel

One page, shown while its `value` is selected. Sets the heading level one below the page title.

Slot: `cl-profile-content-panel`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` |  | The page it shows for. Matches a `Profile.NavItem` value. |

## Examples

### A two-page profile

```tsx
<Profile.Root value={page} onValueChange={setPage}>
  <Profile.Title>User profile</Profile.Title>
  <Profile.Nav>
    <Profile.NavItem value='account'>Account</Profile.NavItem>
    <Profile.NavItem value='security'>Security</Profile.NavItem>
  </Profile.Nav>
  <Profile.Content pageTitle={titles[page]}>
    <Profile.ContentPanel value='account'>…</Profile.ContentPanel>
    <Profile.ContentPanel value='security'>…</Profile.ContentPanel>
  </Profile.Content>
</Profile.Root>
```

## Related

- [Panel](/docs/components/panel.md)
- [Dialog](/docs/components/dialog.md)
- [Tabs](/docs/components/tabs.md)
