# Bento Grid

> A grid of soft gray cards that show off features, each with a live preview, an icon, or a link.

- Name: `bento-grid`
- Status: beta
- Categories: features, bento, marketing
- Files: the install writes `bento-grid.tsx`, and any part files named `bento-grid-*.tsx`, to your `components` alias, `@/components` by default. Edit them freely. They are yours.
- Gallery: https://arbokui.com/website/bento-grid
- Registry item: https://arbokui.com/r/bento-grid.json

## Install

1. Add the registry to `components.json`. Do this first, once:

   ```bash
   npx shadcn@latest registry add "@arbokui=https://arbokui.com/r/{name}.json"
   ```

   The command writes this entry. You can also add it by hand:

   ```json
   {
     "registries": {
       "@arbokui": "https://arbokui.com/r/{name}.json"
     }
   }
   ```

   Without this step, the shadcn CLI looks up `@arbokui` in a public list that Arbokui does not control.

2. Add the theme once per app. It replaces your color tokens with ones checked for contrast:

   ```bash
   npx shadcn@latest add @arbokui/theme
   ```

3. Add the website component. It also adds every component it uses:

   ```bash
   npx shadcn@latest add @arbokui/bento-grid
   ```

## Use it for

- The feature sections of a landing page, under a Headline.
- A showcase: three cards, each with a \`label\`, a \`preview\` built from real parts, and a \`description\` at the bottom.
- Feature cards: an \`icon\`, a \`title\`, and a \`description\`, with a \`preview\` above them if you have one. Use size lg for three big ones.
- A feature list: up to nine cards with only an icon, title, and description.
- Give a card an \`href\` when a page tells more. The whole card becomes the link, and an arrow shows.
- Make one card wider with className="@3xl:col-span-2".

## Avoid it for

- Numbers people check, like a dashboard's key stats. Use Stats Cards.
- Screenshots as previews. Build them from parts, so they stay sharp and follow the theme.
- More than nine cards in one grid. Split them under two Headlines.

## Props

- `label`: `string`. BentoCard. A small label at the top.
- `preview`: `ReactNode`. BentoCard. A live mock of the feature. With a title under it, its bottom fades out.
- `icon`: `ReactNode`. BentoCard. An icon over the title, in the brand color, drawn at 28px.
- `title`: `ReactNode`. BentoCard. What the feature is. It is an h3, and it names the link.
- `description`: `ReactNode`. BentoCard. What it does. Without a title, it sits at the bottom of the card.
- `href`: `string`. BentoCard. Where the card leads. Needs a title, which becomes the link text.
- `renderLink`: `(props: BentoLinkProps) => ReactNode`. Default `a plain <a>`. BentoCard. Draws the link. Spread the props onto your router's link: (props) => \<Link {...props} />.
- `pattern`: `boolean`. Default `false`. BentoCard. A field of dots fading down from the top edge, in the card's tone.
- `tone`: `"neutral" | "brand" | "danger" | "success" | "warning"`. Default `"neutral"`. BentoCard. The color of the dots.
- `size`: `"md" | "lg"`. Default `"md"`. BentoCard. Text size: 13px for a grid of many cards, 16px for a few big ones.
- `className`: `string`. Extra classes on the root. On BentoGrid it holds the container query.
- `BentoGrid`: `ComponentProps<"div">`. Part. The grid: one column when narrow, three from 48rem of its own width. Put BentoCards inside.

## Accessibility

- Each title is an h3, so put the grid under an h2, like a Headline.
- With an href, the link is the title, stretched over the card. Screen readers hear one link with the title as its name.
- A focused link outlines the whole card.
- Icons, arrows, and the dot pattern are aria-hidden.
- A preview is a picture of the product. Keep it free of real buttons, so nothing inside it takes focus.
- In forced colors the preview's fade is turned off, so nothing is hidden.
- In forced colors each card gets a border, so its edge still shows when its fill is painted away.

## Examples

### Three showcase cards

```tsx
<BentoGrid>
  <BentoCard label="Everyone answers" preview={<AnswersMock />} pattern tone="success" description="Every event has an answer-by date." />
  <BentoCard label="Watch the count" preview={<CountsMock />} pattern tone="danger" description="The number going sits on the event." />
  <BentoCard label="Set the team up" preview={<RolesMock />} pattern tone="brand" description="Leads plan, everyone answers." />
</BentoGrid>
```

### A feature list with links

```tsx
<BentoGrid>
  <BentoCard icon={<Calendar />} title="Calendar feed" description="Add it once and it stays up to date." href="/features/calendar" />
  <BentoCard icon={<Mail />} title="Reminder emails" description="Chase the people who haven't answered." href="/features/reminders" />
  <BentoCard icon={<Download />} title="Download your data" description="Anyone can take their data with them." />
</BentoGrid>
```