# Profile settings

A shadcn/ui settings block for SaaS apps: profile photo, name, username and bio with one save bar, plus emails, passkeys and Google or GitHub sign-in.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown variants are available for the docs, pricing and about pages: append `.md` to the URL or send an `Accept: text/markdown` header (the home page answers the header too). An agent skill is available at [/.well-known/agent-skills/site-skill.md](/.well-known/agent-skills/site-skill.md).

## At a glance

- **Good for:** Account settings in SaaS apps; Profile pages for team workspaces; Apps with social and passkey sign-in; Admin and user dashboards
- **Category:** Settings & account › Profile · **Type:** Settings, Forms · **Style:** Motion, Minimal, Dark mode
- **See it:** [Live preview](https://www.craftui.space/docs/blocks/profile-settings) · [Screenshot](https://www.craftui.space/llms.md/preview/profile-settings.5ca2228c.jpg)

![Profile settings](https://www.craftui.space/llms.md/preview/profile-settings.5ca2228c.jpg)

## Install

```bash
pnpm dlx shadcn@latest add https://www.craftui.space/r/profile-settings.json
```

This is a paid item (BLK-WKGE5B): the install needs a craftUI plan or a purchase of it. Signed in, the docs page gives your personal install command. Plans: https://www.craftui.space/pricing

## Usage

```tsx
import ProfileSettings from "@/components/blocks/profile-settings/profile-settings";

export default function Page() {
  return <ProfileSettings />;
}
```

With no props it renders with demo content; pass your own through the props below.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultValues` | `ProfileValues` | `built-in demo value` | The profile as it's saved now. Defaults to a demo profile (Sam Davies). |
| `onSave` | `(values: ProfileValues) => Promise<void>` | `async () => { await wait(900); }` | Saves the changed profile. Resolve once it's stored; reject to keep the changes and show "Changes not saved". Defaults to a 0.9s demo save. |
| `checkUsername` | `(username: string) => Promise<boolean>` | `async (username: string) => { await wait(300); return !DEMO_TAKEN.has(username)…` | Resolves `true` when a username is free. Called 450ms after typing stops. Defaults to a demo where admin, acme, root, sam and support are taken. |
| `uploadAvatar` | `(file: File) => Promise<string>` | — | Uploads a picked photo and resolves to its URL, which goes into the profile on Save. Defaults to a local preview URL (nothing is uploaded). |
| `emails` | `EmailSettings` | `built-in demo value` | The primary and secondary email, and what to call when they change. Defaults to a demo. |
| `signIn` | `SignInSettings` | `built-in demo value` | Passkeys and sign-in providers, and what to call when they change. Defaults to a demo. |
| `productName` | `string` | `"Acme"` | Your product's name, used in the descriptions ("across Acme"). Defaults to "Acme". |
| `usernamePrefix` | `string` | `"acme.com/"` | Shown before the username: your profile URL. Defaults to "acme.com/". |
| `bioMaxLength` | `number` | `160` | Longest bio, in characters. Defaults to 160. |
| `avatarMaxMb` | `number` | `2` | Largest photo, in megabytes. Defaults to 2. |
| `nav` | `SettingsNavGroup[]` | `DEFAULT_SETTINGS_NAV` | The settings nav, in groups. Defaults to Account and Workspace. |
| `activeItem` | `string` | `"profile"` | Id of the current nav item. Defaults to "profile". |
| `onNavigate` | `SettingsNavigateHandler` | — | Runs before a nav link is followed: route with your router here. While there are unsaved changes the block stays and nudges the save bar. |
| `className` | `string` | — | Extra classes for the root element. |

### `ProfileValues`

| Field | Type | Description |
| --- | --- | --- |
| `avatar` (required) | `string \| null` | Photo URL, or `null` to show initials. |
| `name` (required) | `string` | Full name, e.g. "Sam Davies". |
| `username` (required) | `string` | Username without the prefix, e.g. "samdavies": 3–20 lowercase letters, numbers or _. |
| `bio` (required) | `string` | A line or two about the person. |

### `EmailSettings`

| Field | Type | Description |
| --- | --- | --- |
| `primary` (required) | `EmailAddress` | The address the person signs in with. |
| `secondary` (required) | `EmailAddress \| null` | An optional second address, for account recovery. `null` for none. |
| `onSendLink` (required) | `(kind: EmailKind, address: string) => Promise<void>` | Sends a confirmation link to a new primary or secondary address. |
| `onResendLink` (required) | `(address: string) => Promise<void>` | Sends the confirmation link again to an unverified address. |
| `onRemoveSecondary` (required) | `() => Promise<void> \| void` | Removes the secondary address. |

### `SignInSettings`

| Field | Type | Description |
| --- | --- | --- |
| `providers` (required) | `SignInProvider[]` | Every provider you offer; the connected ones have an `account`. |
| `passkeys` (required) | `Passkey[]` | The passkeys registered on the account. |
| `onConnect` (required) | `(id: string) => Promise<string>` | Connects a provider (open its sign-in window); resolves to the account it connected. |
| `onDisconnect` (required) | `(id: string) => Promise<void> \| void` | Disconnects a provider. |
| `onAddPasskey` (required) | `() => Promise<Passkey>` | Registers a new passkey (run the browser's WebAuthn prompt); resolves to it. |
| `onRemovePasskey` (required) | `(id: string) => Promise<void> \| void` | Removes a passkey. |

### `SettingsNavGroup`

| Field | Type | Description |
| --- | --- | --- |
| `label` | `string` | Small heading above the group, e.g. "Workspace". Leave out for none. |
| `items` (required) | `SettingsNavItem[]` | The links in the group, in order. |

### `EmailAddress`

| Field | Type | Description |
| --- | --- | --- |
| `address` (required) | `string` | The address, e.g. "sam@acme.com". |
| `verified` (required) | `boolean` | Whether the person has confirmed it from the link sent to it. |

### `SignInProvider`

| Field | Type | Description |
| --- | --- | --- |
| `id` (required) | `string` | Unique id, e.g. "google". "google", "github", "apple", "microsoft" and "gitlab" get their logo built in. |
| `name` (required) | `string` | Name shown in the list, e.g. "Google". |
| `account` | `string` | The account it's connected to, e.g. "sam@gmail.com". Leave out when not connected. |
| `lastUsed` | `string \| null` | Day it last signed the person in, as YYYY-MM-DD. `null` when connected but not used yet. |
| `logo` | `React.ReactNode` | Your own logo (about 20px), for a provider without a built-in one. |

### `Passkey`

| Field | Type | Description |
| --- | --- | --- |
| `id` (required) | `string` | Unique id. |
| `name` (required) | `string` | The device or password manager it lives in, e.g. "MacBook Pro". |
| `added` (required) | `string` | Day it was added, as YYYY-MM-DD. |
| `lastUsed` (required) | `string \| null` | Day it last signed the person in, as YYYY-MM-DD, or `null` if never. |

### `SettingsNavItem`

| Field | Type | Description |
| --- | --- | --- |
| `id` (required) | `string` | Unique id; matched against `activeItem` to mark the current page. |
| `label` (required) | `string` | Text shown in the nav, e.g. "Security". |
| `icon` (required) | `typeof UserIcon` | A Hugeicons icon from `@hugeicons/core-free-icons`, e.g. `UserIcon`. |
| `href` (required) | `string` | Where the link goes, e.g. "/settings/security". |

## Files

The install adds:

- `components/blocks/profile-settings/profile-settings.tsx`
- `components/blocks/profile-settings/settings-nav.tsx`
- `components/blocks/profile-settings/profile-fields.tsx`
- `components/blocks/profile-settings/email-field.tsx`
- `components/blocks/profile-settings/sign-in-methods.tsx`
- `components/blocks/profile-settings/save-bar.tsx`
- `components/blocks/profile-settings/motion.tsx`
- `components/blocks/profile-settings/status-button.tsx`
- `components/blocks/profile-settings/surface.ts`

npm dependencies (installed for you): `@hugeicons/core-free-icons`, `@hugeicons/react`, `motion`.

shadcn/ui components it uses (the shadcn CLI adds any that are missing): `avatar`, `button`, `dropdown-menu`, `input`, `kbd`, `textarea`.