# Frame

Lays out a header, body, and footer in a column.

[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Frame.tsx)

## Overview

A frame lays out a header, body, and footer in a column with no fill. Wrap it in a [Surface](/docs/components/surface) for a card, or put it in a [Dialog](/docs/components/dialog) or [Drawer](/docs/components/drawer) popup.

The actions share the width of the footer equally.

## Examples

### Basic

```tsx
import { Button, Frame, ListGroup, Surface } from '@tempoxyz/ds'

export function Demo() {
  return (
    <Surface>
      <Frame.Root onDismiss={() => {}}>
        <Frame.Header>
          <Frame.Title>Review request</Frame.Title>
          <Frame.Description>Review the details before continuing.</Frame.Description>
          <Frame.Close />
        </Frame.Header>
        <Frame.Body>
          <ListGroup>
            <ListGroup.Row>
              <ListGroup.Label>Network</ListGroup.Label>
              Tempo
            </ListGroup.Row>
            <ListGroup.Row>
              <ListGroup.Label>Amount</ListGroup.Label>
              $50.00
            </ListGroup.Row>
          </ListGroup>
        </Frame.Body>
        <Frame.Footer>
          <Frame.Actions>
            <Button variant="secondary">Cancel</Button>
            <Button>Approve</Button>
          </Frame.Actions>
        </Frame.Footer>
      </Frame.Root>
    </Surface>
  )
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Frame/Basic.tsx)

### OnDismiss

Set `onDismiss` on the frame or a surrounding `Frame.Provider` to show `Frame.Close`.

```tsx
import { Button, Frame, ListGroup, style, Surface } from '@tempoxyz/ds'

export function Demo() {
  return (
    <Frame.Provider onDismiss={() => {}}>
      <div {...styles.grid()}>
        <Surface>
          <Review />
        </Surface>
        <Review />
        <Surface>
          <Review onDismiss={null} />
        </Surface>
      </div>
    </Frame.Provider>
  )
}

function Review(props: Frame.Root.Props) {
  return (
    <Frame.Root {...props}>
      <Frame.Header>
        <Frame.Title>Review request</Frame.Title>
        <Frame.Description>Review the details before continuing.</Frame.Description>
        <Frame.Close />
      </Frame.Header>
      <Frame.Body>
        <ListGroup>
          <ListGroup.Row>
            <ListGroup.Label>Network</ListGroup.Label>
            Tempo
          </ListGroup.Row>
          <ListGroup.Row>
            <ListGroup.Label>Amount</ListGroup.Label>
            $50.00
          </ListGroup.Row>
        </ListGroup>
      </Frame.Body>
      <Frame.Footer>
        <Frame.Actions>
          <Button variant="secondary">Cancel</Button>
          <Button>Approve</Button>
        </Frame.Actions>
      </Frame.Footer>
    </Frame.Root>
  )
}

namespace styles {
  export const grid = style({
    backgroundColor: 'background.primary',
    display: 'grid',
    gap: '16',
    padding: '16',
    gridTemplateColumns: 'repeat(auto-fill, minmax(20rem, 1fr)) !custom',
  })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Frame/OnDismiss.tsx)

## Anatomy

Import the component and assemble its parts.

```tsx
import { Frame } from '@tempoxyz/ds'

<Frame />

<Frame.Provider>
  <Frame.Root>
    <Frame.Header>
      <Frame.Title />
      <Frame.Description />
      <Frame.Close />
    </Frame.Header>
    <Frame.Body />
    <Frame.Footer>
      <Frame.Actions />
    </Frame.Footer>
  </Frame.Root>
</Frame.Provider>
```

## Guidelines

### When to Use

* Give a card, dialog, or drawer a title, content, and a row of actions.
* Share one dismiss handler across nested panels with `Frame.Provider`, such as the steps of a dialog.

### When Not to Use

* Use [Surface](/docs/components/surface) with `Surface.Header` and `Surface.Title` for a card with only a heading and content.
* Use [AppShell](/docs/components/app-shell) for the frame of a whole page.
* Use [Stack](/docs/components/stack) for a plain column without a header or footer.

### Put Actions in the Footer

Put `Frame.Actions` inside `Frame.Footer`, in the [Button](/docs/components/button) order. `Frame.Body` grows to fill the frame, so the footer stays at the bottom of a tall container, such as a dialog popup. The body never scrolls, so let the container handle overflow.

**Do:** Keep the actions in `Frame.Footer`, at the bottom of the frame.

```tsx
/**
 * Do example for "Put Actions in the Footer" on the Frame page.
 * Keep the actions in `Frame.Footer`, at the bottom of the frame.
 * @module
 */
import { Amount, Button, Frame, ListGroup, style, Surface } from '@tempoxyz/ds'

const payments = [
  ['Alice', '25.00'],
  ['Bob', '120.00'],
] as const

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.canvas()}>
      <Surface size="medium" {...styles.card()}>
        <Frame {...styles.frame()}>
          <Frame.Header>
            <Frame.Title>Review batch</Frame.Title>
          </Frame.Header>
          <Frame.Body>
            <ListGroup>
              {payments.map(([name, amount]) => (
                <ListGroup.Row key={name}>
                  <ListGroup.Label>{name}</ListGroup.Label>
                  <Amount symbol="USDC" value={amount} />
                </ListGroup.Row>
              ))}
            </ListGroup>
          </Frame.Body>
          <Frame.Footer>
            <Frame.Actions>
              <Button size="small" variant="secondary">
                Cancel
              </Button>
              <Button size="small">Send 2 payments</Button>
            </Frame.Actions>
          </Frame.Footer>
        </Frame>
      </Surface>
    </div>
  )
}

namespace styles {
  export const canvas = style({
    backgroundColor: 'background.primary',
    borderRadius: 'sm',
    boxSizing: 'border-box',
    padding: '12',
    width: '100% !custom',
  })

  export const card = style({ height: '240' })

  export const frame = style({ height: '100% !custom', rowGap: '16' })
}
```

**Don't:** Put the actions at the end of `Frame.Body`, directly against the content.

```tsx
/**
 * Don't example for "Put Actions in the Footer" on the Frame page.
 * Don't put the actions at the end of `Frame.Body`, directly against the content.
 * @module
 */
import { Amount, Button, Frame, ListGroup, style, Surface } from '@tempoxyz/ds'

const payments = [
  ['Alice', '25.00'],
  ['Bob', '120.00'],
] as const

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.canvas()}>
      <Surface size="medium" {...styles.card()}>
        <Frame {...styles.frame()}>
          <Frame.Header>
            <Frame.Title>Review batch</Frame.Title>
          </Frame.Header>
          <Frame.Body>
            <ListGroup>
              {payments.map(([name, amount]) => (
                <ListGroup.Row key={name}>
                  <ListGroup.Label>{name}</ListGroup.Label>
                  <Amount symbol="USDC" value={amount} />
                </ListGroup.Row>
              ))}
            </ListGroup>
            <Frame.Actions>
              <Button size="small" variant="secondary">
                Cancel
              </Button>
              <Button size="small">Send 2 payments</Button>
            </Frame.Actions>
          </Frame.Body>
        </Frame>
      </Surface>
    </div>
  )
}

namespace styles {
  export const canvas = style({
    backgroundColor: 'background.primary',
    borderRadius: 'sm',
    boxSizing: 'border-box',
    padding: '12',
    width: '100% !custom',
  })

  export const card = style({ height: '240' })

  export const frame = style({ height: '100% !custom', rowGap: '16' })
}
```

### Show Close Only When It Dismisses

If a nested frame can't be dismissed, such as a confirmation step, pass `onDismiss={null}` to drop the inherited handler and hide `Frame.Close`.

**Do:** Pass `onDismiss={null}` on a step that must finish.

```tsx
/**
 * Do example for "Show Close Only When It Dismisses" on the Frame page.
 * Pass `onDismiss={null}` on a step that must finish.
 * @module
 */
import { Button, Frame, style, Surface } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Frame.Provider onDismiss={() => {}}>
      <div {...styles.canvas()}>
        <Surface size="medium">
          <Frame onDismiss={null}>
            <Frame.Header>
              <Frame.Title>Sending payment</Frame.Title>
              <Frame.Description>Keep this window open until 25.00 USDC settles.</Frame.Description>
              <Frame.Close />
            </Frame.Header>
            <Frame.Footer>
              <Frame.Actions>
                <Button loading size="small">
                  Send
                </Button>
              </Frame.Actions>
            </Frame.Footer>
          </Frame>
        </Surface>
      </div>
    </Frame.Provider>
  )
}

namespace styles {
  export const canvas = style({
    backgroundColor: 'background.primary',
    borderRadius: 'sm',
    boxSizing: 'border-box',
    padding: '12',
    width: '100% !custom',
  })
}
```

**Don't:** Leave an inherited close button on a step that can't be dismissed.

```tsx
/**
 * Don't example for "Show Close Only When It Dismisses" on the Frame page.
 * Don't leave an inherited close button on a step that can't be dismissed.
 * @module
 */
import { Button, Frame, style, Surface } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Frame.Provider onDismiss={() => {}}>
      <div {...styles.canvas()}>
        <Surface size="medium">
          <Frame>
            <Frame.Header>
              <Frame.Title>Sending payment</Frame.Title>
              <Frame.Description>Keep this window open until 25.00 USDC settles.</Frame.Description>
              <Frame.Close />
            </Frame.Header>
            <Frame.Footer>
              <Frame.Actions>
                <Button loading size="small">
                  Send
                </Button>
              </Frame.Actions>
            </Frame.Footer>
          </Frame>
        </Surface>
      </div>
    </Frame.Provider>
  )
}

namespace styles {
  export const canvas = style({
    backgroundColor: 'background.primary',
    borderRadius: 'sm',
    boxSizing: 'border-box',
    padding: '12',
    width: '100% !custom',
  })
}
```

### Check the Heading Level

`Frame.Title` always renders an `h2`.

* **Dialog or Card (h2):** Use `Frame.Title` in a dialog, or in a card below the page `h1`.
* **Inside an h2 Section (h3):** Render your own `h3` in the header in place of `Frame.Title`.

## Content

* **Title:** Name the task, such as Review request or Send USDC.
* **Description:** In one sentence, state what happens next.
* **Primary action:** Repeat the title's verb, such as Approve request.

## Accessibility

A frame adds headings and an optional close button. It doesn't move or trap focus, so other semantics and focus management come from its container.

### Semantics

* **Frame.Title (h2):** The frame's heading, rendered at the top of its header.
* **Frame.Description (p):** Supporting text below the title, which describes the frame's content.
* **Frame.Close (button):** Announced as "Close", with its icon hidden. Its target exceeds the WCAG 2.2 minimum.
* **No Inert Close Button:** The close button renders nothing without a dismiss handler or `onClick`.

### Keyboard

* **Move Through the Frame (Tab):** Moves focus to the close button and the controls, in source order.
* **Activate Close (Enter or Space):** Calls the close button's `onClick`, then the dismiss handler.

### Your Responsibilities

* **Name the Close Button (aria-label):** If ambiguous, name what it closes: "Close send payment".
* **Label the Dialog (aria-labelledby):** Point a dialog's `aria-labelledby` at the title.

## Related

[Surface](/docs/components/surface)

Use for the card around a frame.

[Dialog](/docs/components/dialog)

Use for frames that open over the page.

[Drawer](/docs/components/drawer)

Use for side panels.

[Button](/docs/components/button)

Use for ordering actions.
