# Card

The surface a flow renders on: header, message slot, content and footer, signed with "Secured by Clerk". Rendered as the content of a `Dialog.Popup`, the title and description name the dialog and the header carries its close button.

## Use for

- the surface a sign-in, sign-up or profile screen renders on
- the content of a dialog, with a title, description and footer actions
- a form-level error above a form, with `Card.Banner`

## Practices

- Do: Pass `renderBranding` from the host, such as `displayConfig.branded`, on a connected surface.
- Do: Keep `Card.Banner` rendered with `role='alert'` and pass it the message, or nothing. It collapses while empty, so the live region is in place before the message arrives.
- Don't: Add a close button to a card in a dialog. `Card.Header` renders one when the dialog shows it.
- Don't: Pass `id` to `Card.Title` or `Card.Description` in a dialog. The dialog owns both ids.
- Don't: Render `Card.Root` in a screen or a `*Steps` component. The rules are in the Views guide (`mosaic guides inspect views`).

## API reference

### Card.Root

The surface. Draws the card treatment only when it is the outermost card in its dialog and not `flush`. Appends the branding when `renderBranding`.

Slot: `cl-card-root`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `elevation` | `CardElevation` | `'card'` | `card`, `flush` or `overlay`. |
| `size` | `CardSize` | `'md'` | Width. `lg` is for forms that need the room, like a tag input. |
| `align` | `CardAlign` | `'start'` | Aligns every `Card.Header`: `start` or `center`. |
| `renderBranding` | `boolean` | `true` | Signs the foot of the card with "Secured by Clerk". |

### Card.Header

Holds the media, title and description in `cl-card-header-content`. Inside a dialog with `showCloseButton`, renders a close button first, so it takes the dialog's opening focus.

Slot: `cl-card-header`

### Card.Media

An icon or image above the title, aligned with the header.

Slot: `cl-card-media`

### Card.Title

An `h2`. In a dialog, on the active flow step, takes the id the popup is labelled by.

Slot: `cl-card-title`

### Card.Description

A `p`. In a dialog, on the active flow step, takes the id the popup is described by.

Slot: `cl-card-description`

### Card.Banner

A message slot between the header and the content. Expands into a `Banner` while its children hold a message and collapses when they are empty.

Slot: `cl-card-banner`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `color` | `BannerRootProps['color']` | `'neutral'` | The banner color. |

### Card.Content

The body.

Slot: `cl-card-content`

### Card.Footer

The actions row. Buttons inside default to `fullWidth`. Carries `data-elevation`.

Slot: `cl-card-footer`

## Examples

### A card with a form error

```tsx
<Card.Root renderBranding={renderBranding}>
  <Card.Header>
    <Card.Title>{m.title}</Card.Title>
    <Card.Description>{m.description}</Card.Description>
  </Card.Header>
  <Card.Banner role='alert' color='negative'>
    {form.error}
  </Card.Banner>
  <Card.Content>…</Card.Content>
  <Card.Footer>…</Card.Footer>
</Card.Root>
```

## Related

- [Dialog](/docs/components/dialog.md)
- [Banner](/docs/components/banner.md)
- [Flow](/docs/components/flow.md)
- [Branding](/docs/components/branding.md)
