# Frame

A tinted shell with an optional header around a raised body.

Source: [frame.tsx](https://github.com/jakejarvis/jarvis-ui/blob/main/src/components/ui/frame.tsx)

```tsx
import { RocketIcon } from "lucide-react";
import { Fragment } from "react";

import { Button } from "@/components/ui/button";
import { Frame, FrameActions, FrameBody, FrameHeader, FrameTitle } from "@/components/ui/frame";
import {
  Item,
  ItemActions,
  ItemContent,
  ItemDescription,
  ItemGroup,
  ItemSeparator,
  ItemTitle,
} from "@/components/ui/item";
import { Status } from "@/components/ui/status";

const deployments = [
  {
    branch: "main",
    message: "Fix pricing table alignment",
    time: "3 min ago",
    status: "success",
    label: "Ready",
  },
  {
    branch: "feature/search",
    message: "Add search to the docs",
    time: "12 min ago",
    status: "warning",
    label: "Building",
  },
  {
    branch: "fix/og-images",
    message: "Draw Open Graph images in dark mode",
    time: "1 hour ago",
    status: "destructive",
    label: "Failed",
  },
] as const;

export default function FrameDemo() {
  return (
    <Frame className="w-full max-w-md">
      <FrameHeader>
        <RocketIcon />
        <FrameTitle>Deployments</FrameTitle>
        <FrameActions>
          <Button variant="ghost" size="xs">
            View all
          </Button>
        </FrameActions>
      </FrameHeader>
      <FrameBody>
        <ItemGroup className="gap-0">
          {deployments.map((deployment, index) => (
            <Fragment key={deployment.branch}>
              {index > 0 && <ItemSeparator className="my-0" />}
              <Item size="sm" className="rounded-none">
                <ItemContent>
                  <ItemTitle>{deployment.message}</ItemTitle>
                  <ItemDescription>
                    {deployment.branch} · {deployment.time}
                  </ItemDescription>
                </ItemContent>
                <ItemActions>
                  <Status variant={deployment.status}>{deployment.label}</Status>
                </ItemActions>
              </Item>
            </Fragment>
          ))}
        </ItemGroup>
      </FrameBody>
    </Frame>
  );
}
```

## Installation

Add the registry, once per project:

```bash
npx shadcn@latest registry add @jarvis=https://ui.jarv.is/r/{name}.json
```

Then add the component:

```bash
npx shadcn@latest add @jarvis/frame
```

## Usage

```tsx
import { Button } from "@/components/ui/button";
import { Frame, FrameActions, FrameBody, FrameHeader, FrameTitle } from "@/components/ui/frame";

export function Deployments() {
  return (
    <Frame>
      <FrameHeader>
        <FrameTitle>Deployments</FrameTitle>
        <FrameActions>
          <Button variant="ghost" size="xs">
            View all
          </Button>
        </FrameActions>
      </FrameHeader>
      <FrameBody>…</FrameBody>
    </Frame>
  );
}
```

A Frame with a `FrameHeader` or a `FrameFooter` leaves a narrow margin around its parts, and
`FrameBody` sits in it as a raised panel. With neither, the body fills the frame.

The same shell holds [Code Block](https://ui.jarv.is/components/code-block.md),
[JSON Viewer](https://ui.jarv.is/components/json-viewer.md), [Package Command](https://ui.jarv.is/components/package-command.md) and
[Table](https://ui.jarv.is/components/table.md), which render Frame's parts under their own `data-slot`. `FrameHeader`
and `FrameFooter` always keep `data-frame="header"` and `data-frame="footer"`. Frame's layout reads
those, so a header or footer renamed this way still insets the body.

## Composition

- `Frame`
  - `FrameHeader`
    - `FrameTitle`
    - `FrameActions`
  - `FrameBody`
  - `FrameFooter`
    - `FrameActions`

## Examples

### With a footer

`FrameFooter` sits below the body, for a count, a status or a link to more. A `FrameActions` in it
moves to the end of the row.

```tsx
import { Fragment } from "react";

import { Button } from "@/components/ui/button";
import { Frame, FrameActions, FrameBody, FrameFooter } from "@/components/ui/frame";
import {
  Item,
  ItemActions,
  ItemContent,
  ItemDescription,
  ItemGroup,
  ItemSeparator,
  ItemTitle,
} from "@/components/ui/item";

const invoices = [
  { id: "INV-1046", customer: "Evergreen Co.", amount: "$1,280.00", due: "Due April 2" },
  { id: "INV-1045", customer: "Driftwood Labs", amount: "$4,150.00", due: "Due March 28" },
  { id: "INV-1044", customer: "Cedar & Pine", amount: "$960.00", due: "Due March 24" },
];

export default function FrameWithFooter() {
  return (
    <Frame className="w-full max-w-md">
      <FrameBody>
        <ItemGroup className="gap-0">
          {invoices.map((invoice, index) => (
            <Fragment key={invoice.id}>
              {index > 0 && <ItemSeparator className="my-0" />}
              <Item size="sm" className="rounded-none">
                <ItemContent>
                  <ItemTitle>{invoice.customer}</ItemTitle>
                  <ItemDescription>
                    {invoice.id} · {invoice.due}
                  </ItemDescription>
                </ItemContent>
                <ItemActions className="tabular-nums">{invoice.amount}</ItemActions>
              </Item>
            </Fragment>
          ))}
        </ItemGroup>
      </FrameBody>
      <FrameFooter>
        Showing 3 of 24 invoices
        <FrameActions>
          <Button variant="ghost" size="xs">
            View all
          </Button>
        </FrameActions>
      </FrameFooter>
    </Frame>
  );
}
```

### Without a header

With neither a header nor a footer, the body fills the frame, and the frame's edge draws over it.

```tsx
import { Frame, FrameBody } from "@/components/ui/frame";

const usage = [
  { label: "Plan", value: "Team" },
  { label: "Seats", value: "12 of 25" },
  { label: "Storage", value: "6.4 of 10 GB" },
  { label: "Renews", value: "April 1, 2026" },
];

export default function FrameWithoutHeader() {
  return (
    <Frame className="w-full max-w-xs">
      <FrameBody className="flex flex-col gap-2 p-3 text-sm">
        {usage.map((row) => (
          <div key={row.label} className="flex items-center justify-between gap-4">
            <span className="text-muted-foreground">{row.label}</span>
            <span className="tabular-nums">{row.value}</span>
          </div>
        ))}
      </FrameBody>
    </Frame>
  );
}
```

### Scrolling

Give `FrameBody` a [Scroll Area](https://ui.jarv.is/components/scroll-area.md) through `render` and a height, so the body
scrolls while the header stays in place.

```tsx
import { ScrollTextIcon } from "lucide-react";

import { CopyButton } from "@/components/ui/copy-button";
import { Frame, FrameActions, FrameBody, FrameHeader, FrameTitle } from "@/components/ui/frame";
import { ScrollArea } from "@/components/ui/scroll-area";

const log = [
  "Cloning github.com/example/site (branch: main)",
  "Installing dependencies with pnpm",
  "Packages: +412",
  "Done in 6.2s",
  "Running build: pnpm build",
  "Typechecking 184 files",
  "Prerendering 96 pages",
  "Writing sitemap.xml",
  "Compressing 312 static files",
  "Uploading build output",
  "Assigning example.com",
  "Deployment ready in 48s",
];

export default function FrameScrollArea() {
  return (
    <Frame className="w-full max-w-md">
      <FrameHeader>
        <ScrollTextIcon />
        <FrameTitle>Build log</FrameTitle>
        <FrameActions>
          <CopyButton value={log.join("\n")} size="icon-xs" aria-label="Copy log" />
        </FrameActions>
      </FrameHeader>
      <FrameBody render={<ScrollArea />} className="h-40 [--scroll-fade-size:1rem]">
        <ol className="flex flex-col py-2 font-mono text-xs leading-5">
          {log.map((line, index) => (
            <li key={line} className="flex gap-3 px-3">
              <span className="w-4 shrink-0 text-right text-faint tabular-nums select-none">
                {index + 1}
              </span>
              <span className="min-w-0 truncate">{line}</span>
            </li>
          ))}
        </ol>
      </FrameBody>
    </Frame>
  );
}
```

## Props

| Part | Extends |
| --- | --- |
| `Frame` | `<div>` |
| `FrameHeader` | `<div>` |
| `FrameTitle` | `<span>` |
| `FrameActions` | `<div>` |
| `FrameBody` | `<div>` |
| `FrameFooter` | `<div>` |

Base UI's [styling](https://base-ui.com/react/handbook/styling) and [composition](https://base-ui.com/react/handbook/composition) guides say more about `className`, `style` and `render`.

### Frame

| Prop         | Type                                                     | Default | Description                                                                                                                                                                               |
| ------------ | -------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `className?` | `string`                                                 | —       | CSS class applied to the element.                                                                                                                                                         |
| `style?`     | `React.CSSProperties`                                    | —       | Style applied to the element.                                                                                                                                                             |
| `render?`    | `ComponentRenderFn<HTMLProps, {}> \| React.ReactElement` | —       | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |

### FrameHeader

| Prop         | Type                                                     | Default | Description                                                                                                                                                                               |
| ------------ | -------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `className?` | `string`                                                 | —       | CSS class applied to the element.                                                                                                                                                         |
| `style?`     | `React.CSSProperties`                                    | —       | Style applied to the element.                                                                                                                                                             |
| `render?`    | `ComponentRenderFn<HTMLProps, {}> \| React.ReactElement` | —       | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |

### FrameTitle

| Prop         | Type                                                     | Default | Description                                                                                                                                                                               |
| ------------ | -------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `className?` | `string`                                                 | —       | CSS class applied to the element.                                                                                                                                                         |
| `style?`     | `React.CSSProperties`                                    | —       | Style applied to the element.                                                                                                                                                             |
| `render?`    | `ComponentRenderFn<HTMLProps, {}> \| React.ReactElement` | —       | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |

### FrameActions

| Prop         | Type                                                     | Default | Description                                                                                                                                                                               |
| ------------ | -------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `className?` | `string`                                                 | —       | CSS class applied to the element.                                                                                                                                                         |
| `style?`     | `React.CSSProperties`                                    | —       | Style applied to the element.                                                                                                                                                             |
| `render?`    | `ComponentRenderFn<HTMLProps, {}> \| React.ReactElement` | —       | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |

### FrameBody

| Prop         | Type                                                     | Default | Description                                                                                                                                                                               |
| ------------ | -------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `className?` | `string`                                                 | —       | CSS class applied to the element.                                                                                                                                                         |
| `style?`     | `React.CSSProperties`                                    | —       | Style applied to the element.                                                                                                                                                             |
| `render?`    | `ComponentRenderFn<HTMLProps, {}> \| React.ReactElement` | —       | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |

### FrameFooter

| Prop         | Type                                                     | Default | Description                                                                                                                                                                               |
| ------------ | -------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `className?` | `string`                                                 | —       | CSS class applied to the element.                                                                                                                                                         |
| `style?`     | `React.CSSProperties`                                    | —       | Style applied to the element.                                                                                                                                                             |
| `render?`    | `ComponentRenderFn<HTMLProps, {}> \| React.ReactElement` | —       | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
