Skip to main content

Display

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

Hand it to your agent
Add Cover from Ouro UI to this app. Read https://ui.ouroboros.bot/docs/cover.md first and follow it.

Or by hand. Once per app, with Tailwind CSS v4 and an @/* path alias (Ouro HX is built on Base UI, so --base base; skip -t in an existing app):

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

Then the component. From v0.8.0 it installs only the helpers it imports and never touches your stylesheet (Installing):

npx shadcn@latest add ourostack/ouro-ui/cover#v1.3.344

Or, with the @ouro namespace set up:

npx shadcn@latest add @ouro/ouro-base @ouro/cover

Its tests, stories and Playwright spec are optional. They need Vitest 4.1.11 or later, and from v0.8.0 never change a version your app has (Testing):

npx shadcn@latest add ourostack/ouro-ui/cover#v1.3.344 ourostack/ouro-ui/cover-tests#v1.3.344
import { Cover } from "@/components/ouro/cover/cover";

Paths use shadcn's default @/ alias; the CLI rewrites them to yours.

Example

<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.

alt
Type: string
Default: ""
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
Type: string
Layout only: margins, aspect for size="fill" (aspect-video). Appearance classes warn in development.
ref
Type: Ref<HTMLDivElement>
Reaches the rendered element.
shape
Type: "square" | "rounded"
Default: "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
Type: "sm" | "md" | "lg" | "fill"
Default: "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
Type: 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)
Type: 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.