# Dialog

> A window over the page that holds focus until it closes.

```tsx
import { Button, Dialog, DialogClose, TextField } from '@brand-studio/ui';

export default function DialogDemo() {
  return (
    <Dialog
      trigger={<Button tone="secondary">Edit profile</Button>}
      title="Edit profile"
      description="Changes apply to your next order."
    >
      <div style={{ display: 'grid', gap: 16 }}>
        <TextField label="Name" defaultValue="Sam Rivera" />
        <TextField label="Delivery note" placeholder="Leave by the door" />
      </div>
      <div className="bs-dialog__actions">
        <DialogClose><Button tone="secondary">Cancel</Button></DialogClose>
        <DialogClose><Button>Save</Button></DialogClose>
      </div>
    </Dialog>
  );
}
```

## Installation

```sh
npm install @brand-studio/ui
```

React 18 or 19 is a peer dependency. Import the stylesheet once and wrap the app in a brand theme:

```tsx
import '@brand-studio/ui/styles.css';
import { BrandTheme, Dialog } from '@brand-studio/ui';
import brand from './brand.json';

<BrandTheme palette={brand.tokens} mode="system">
  {/* your app */}
</BrandTheme>
```

## Usage

```tsx
import { Dialog, DialogClose } from '@brand-studio/ui';
```

```tsx
<Dialog trigger={<Button>Open</Button>} title="Edit profile">
  <p>…</p>
  <DialogClose><Button>Done</Button></DialogClose>
</Dialog>
```

## Examples

### Confirmation

Keep the safe choice first and name the action on the button.

```tsx
import { Button, Dialog, DialogClose } from '@brand-studio/ui';

export default function DialogConfirm() {
  return (
    <Dialog
      trigger={<Button>Cancel subscription</Button>}
      title="Cancel your subscription?"
      description="Your last bag ships on Friday. You can restart any time."
    >
      <div className="bs-dialog__actions">
        <DialogClose><Button tone="secondary">Keep it</Button></DialogClose>
        <DialogClose><Button>Cancel subscription</Button></DialogClose>
      </div>
    </Dialog>
  );
}
```

## Accessibility

- Focus moves into the dialog and stays there until it closes.
- Escape, the close button or a click on the backdrop closes it; focus returns to the trigger.
- Page scroll is locked while it is open.
- Wrap any button in `DialogClose` to close the dialog when it is pressed.

## API Reference

### Dialog

| Prop | Type | Default |
|---|---|---|
| `trigger` | `React.ReactElement<unknown, string \| React.JSXElementConstructor<any>>` | – |
| `title` | `string` | – |
| `description?` | `string` | – |
| `children?` | `React.ReactNode` | – |
| `closeLabel?` | `string` | `'Close'` |
| `open?` | `boolean` | – |
| `defaultOpen?` | `boolean` | – |
| `onOpenChange?` | `((open: boolean) => void)` | – |

### DialogClose

| Prop | Type | Default |
|---|---|---|
| `children` | `React.ReactElement<unknown, string \| React.JSXElementConstructor<any>>` | – |

Source: https://brandstudio.js.org/docs/components/dialog/
