# Security settings

A shadcn/ui security settings block: a checkup with status badges, password, two-factor with QR setup and recovery codes, passkeys and sessions.

> 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 security pages for SaaS and fintech apps; Two-factor setup with an authenticator app or text; Reviewing and signing out sessions and devices; Security checkups that nudge people to finish setup
- **Category:** Settings & account › Security · **Type:** Settings, Forms · **Style:** Motion, Minimal, Dark mode
- **See it:** [Live preview](https://www.craftui.space/docs/blocks/security-settings) · [Screenshot](https://www.craftui.space/llms.md/preview/security-settings.08b272d1.jpg)

![Security settings](https://www.craftui.space/llms.md/preview/security-settings.08b272d1.jpg)

## Install

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

This is a paid item (BLK-GKB8JN): 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 SecuritySettings from "@/components/blocks/security-settings/security-settings";

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

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

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultState` | `SecurityState` | — | The account's security as it is now. Defaults to a demo account. |
| `twoFactor` | `TwoFactorFlow` | — | Everything two-factor needs: the `otpauth://` link and secret for the QR code, and the calls that check codes, text codes, make recovery codes and turn a method off. Defaults to a demo where any code works except 000000. |
| `onChangePassword` | `( current: string, next: string, signOutOthers: boolean ) => Promise<void>` | — | Changes the password. Reject with an Error whose message is shown, e.g. "That isn't your current password." Defaults to a 0.8s demo. |
| `onAddPasskey` | `() => Promise<Passkey>` | — | Registers a passkey (run the browser's WebAuthn prompt) and resolves to it. Defaults to a demo. |
| `onRemovePasskey` | `(id: string) => Promise<void>` | — | Removes a passkey. Defaults to a demo. |
| `onSignOutSession` | `(id: string) => Promise<void>` | — | Signs one session out. Defaults to a demo. |
| `onSignOutOtherSessions` | `() => Promise<void>` | — | Signs out every session except this one. Defaults to a demo. |
| `alerts` | `SecurityAlert[]` | — | The email alerts offered. Defaults to new sign-ins, account changes and two-factor changes. |
| `onAlertChange` | `(id: string, value: boolean) => Promise<void>` | — | Saves one alert as soon as it's flipped; reject to flip it back. Defaults to a demo. |
| `recoveryCodesTotal` | `number` | — | How many recovery codes a fresh set has. Defaults to 10. |
| `user` | `{ name: string; email: string }` | — | The signed-in person; a new password may not contain their name or email. Defaults to the demo person. |
| `productName` | `string` | — | Your product's name, used in the copy and the recovery-codes file. Defaults to "Acme". |
| `phoneCountries` | `PhoneCountry[]` | — | Countries for the text-message phone number. Defaults to 44 common ones. |
| `nav` | `SettingsNavGroup[]` | — | The settings nav, in groups. Defaults to Account and Workspace. |
| `activeItem` | `string` | — | Id of the current nav item. Defaults to "security". |
| `onNavigate` | `SettingsNavigateHandler` | — | Runs before a nav link is followed: route with your router here. |
| `className` | `string` | — | Extra classes for the root element. |

### `SecurityState`

| Field | Type | Description |
| --- | --- | --- |
| `passwordChangedAt` (required) | `string` | When the password last changed, as an ISO date. |
| `authenticatorApp` (required) | `boolean` | Whether the authenticator app is set up. |
| `smsPhone` (required) | `string \| null` | The phone that gets text-message codes, or `null` when that's off. |
| `recoveryCodesLeft` (required) | `number` | Recovery codes still unused. |
| `passkeys` (required) | `Passkey[]` | The passkeys registered. |
| `sessions` (required) | `Session[]` | Everywhere the account is signed in. |
| `alerts` (required) | `Record<string, boolean>` | Which email alerts are on, by alert id. |

### `TwoFactorFlow`

| Field | Type | Description |
| --- | --- | --- |
| `otpauthUrl` (required) | `string` | The `otpauth://` link the QR code encodes, made by your server for this account. |
| `secret` (required) | `string` | The same secret, for typing in by hand (shown in groups of four). |
| `verifyApp` (required) | `(code: string) => Promise<boolean>` | Checks a code from the authenticator app; resolve `false` for a wrong one. |
| `sendSms` (required) | `(phone: string) => Promise<void>` | Texts a code to a phone number (with its country code). |
| `verifySms` (required) | `(phone: string, code: string) => Promise<boolean>` | Checks a texted code; resolve `false` for a wrong one. |
| `generateCodes` (required) | `() => Promise<string[]>` | Makes a new set of recovery codes (the old ones stop working). |
| `turnOff` (required) | `(method: TwoFactorMethod) => Promise<void>` | Turns a method off. |

### `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` | When it was added, already formatted, e.g. "Sep 2". |

### `SecurityAlert`

| Field | Type | Description |
| --- | --- | --- |
| `id` (required) | `string` | Unique id, also the key in the saved values. |
| `label` (required) | `string` | What it does when on, e.g. "Email me about new sign-ins". |
| `description` (required) | `string` | One line on when it's sent. |

### `PhoneCountry`

| Field | Type | Description |
| --- | --- | --- |
| `code` (required) | `string` | ISO 3166 two-letter code, e.g. "IN". Also gives the flag and name. |
| `dial` (required) | `string` | International dialling code, e.g. "+91". |

### `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. |

### `Session`

| Field | Type | Description |
| --- | --- | --- |
| `id` (required) | `string` | Unique id. |
| `device` (required) | `"desktop" \| "phone" \| "tablet"` | The kind of device, for its icon. |
| `browser` (required) | `string` | Browser or app, e.g. "Chrome". |
| `os` (required) | `string` | Operating system, e.g. "macOS". |
| `location` (required) | `string` | Where it signed in from, e.g. "Bengaluru, India". |
| `ip` (required) | `string` | IP address. |
| `lastActive` (required) | `string` | Last activity, as an ISO date-time. |
| `current` | `boolean` | True for the session this page is open in. |
| `unrecognized` | `boolean` | Marks a sign-in the person may not recognise (new country, new device). |

### `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/security-settings/security-settings.tsx`
- `components/blocks/security-settings/security-checkup.tsx`
- `components/blocks/security-settings/sign-in-methods.tsx`
- `components/blocks/security-settings/password-field.tsx`
- `components/blocks/security-settings/two-factor.tsx`
- `components/blocks/security-settings/passkeys.tsx`
- `components/blocks/security-settings/sessions.tsx`
- `components/blocks/security-settings/security-alerts.tsx`
- `components/blocks/security-settings/confirm-dialog.tsx`
- `components/blocks/security-settings/status-button.tsx`
- `components/blocks/security-settings/settings-nav.tsx`
- `components/blocks/security-settings/code-input.tsx`
- `components/blocks/security-settings/phone-field.tsx`
- `components/blocks/security-settings/motion.tsx`
- `components/blocks/security-settings/surface.ts`

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

shadcn/ui components it uses (the shadcn CLI adds any that are missing): `button`, `checkbox`, `command`, `dialog`, `input`, `popover`, `switch`.