<!-- Generated by scripts/gen-docs.mts from the JSDoc in registry/. Do not edit; run `pnpm run docs`. -->

# Cover

A thing's cover: its picture, or, without one, the first letter of its title in the theme's heading font on a wash from the muted color toward the primary. Use it beside a recipe, a book or an album in a list row, on a card, or at full width as a page's hero. A theme sets the wash with `--ouro-cover-from` and `--ouro-cover-to`, and the letter's color with `--ouro-cover-ink`.

## Install

Once per app, with Tailwind CSS v4 and an `@/*` path alias (skip `init` in an existing shadcn app), then the component:

```sh
npx shadcn@latest init --base base --preset nova --yes --no-monorepo
npx shadcn@latest add ourostack/ouro-ui/ouro-base#v1.3.344
npx shadcn@latest add ourostack/ouro-ui/cover#v1.3.344
```

More: [Installing](https://ui.ouroboros.bot/docs/installing.md).

```tsx
import { Cover } from "@/components/ouro/cover/cover";
```

## Example

```tsx
<Cover title="Lemon rice" src={recipe.coverUrl} />
```

## Use instead when

- Use `Avatar` instead for a person or an account, and `AspectRatio` instead for a picture that always has one.

## Props

Type: `CoverProps`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `alt` | `string` | `""` | What the cover shows, for a screen reader. Leave it out where the title is already beside the cover, as in a list row: the cover is then decoration. |
| `className` | `string` |  | Layout only: margins, aspect for `size="fill"` (`aspect-video`). Appearance classes warn in development. |
| `ref` | `Ref<HTMLDivElement>` |  | Reaches the rendered element. |
| `shape` | `"square" \| "rounded"` | `"rounded"` | `rounded` (the theme's lg corner) or `square`, for a cover that runs to the edges of its slot, such as a page's hero on a phone. |
| `size` | `"sm" \| "md" \| "lg" \| "fill"` | `"md"` | How big the cover is: `sm` (40px) for a dense row, `md` (56px) for a list row, `lg` (96px) for a card, and `fill`, as wide as its container, for a page's hero (set its aspect with `className`, such as `aspect-video`). |
| `src` | `string` |  | The picture's address. Without it, or when it fails to load, the cover is the title's initial on a tinted tile. |
| `title` (required) | `string` |  | What the cover belongs to: "Lemon rice". Without a picture, its first letter is the tile's mark. Required, so a tile without a picture still has a letter. |

## Native attributes

Also accepts the attributes in React's `HTMLAttributes` (`id`, `aria-*`, event handlers), passed to the rendered element, except those named on this page.

## Don't use

These are not props. Passing one fails the type check with the fix in the error, and in development a console message names the fix.

- `image`: Not a prop. The picture's address is `src`: `<Cover title="…" src={url} />`.
- `initials`: Not a prop. The letter comes from `title`: `<Cover title="Lemon rice" />`.
- `name`: Not a prop. The title is `title`: `<Cover title="Lemon rice" />`.

## `className` is for layout only

Pass margins, width and grid placement (`mt-4`, `w-full`, `col-span-2`).

Appearance comes from props, not classes. In development, a class that sets appearance logs one warning per component instance, naming the prop to use instead. A class sets appearance when, after its variants (`hover:`, `sm:`) and any `!` are removed, it starts with `bg-`, `text-`, `border-`, `rounded-`, `shadow-`, `font-`, `ring-`, `from-`, `via-`, `to-`, `fill-` or `stroke-`, or is `border`, `rounded`, `shadow` or `ring`, or has a `dark:` variant. Text wrapping, overflow and table layout classes (`text-wrap`, `text-ellipsis`, `border-collapse`) are layout and do not warn.

Alignment classes (`text-center`) warn too: set alignment on a parent element.
