Ouro HX

Display

Card

A surface that groups one thing's content: a media slot across the top, a title with a description and an action, a body, and a footer. With href the whole card is one link, named by its title, with one tab stop, and its action and footer controls stay their own.

Pantry

What you have on hand

Flour, rice, black beans, two lemons.

Weeknight dinners

12 recipes

In Spoonjoy

Spoonjoy, a recipe app, is built with Ouro HX (how).

See it live, no sign-in needed: Sign in · Sign up

In its source: app/components/account/AccountDataSection.tsx · app/components/cookbook/KitchenHome.tsx · app/components/moderation/BlockedChefsSection.tsx

Install

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

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/card#v1.2.13

Or, with the @ouro namespace set up:

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

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/card#v1.2.13 ourostack/ouro-ui/card-tests#v1.2.13
import { Card } from "@/components/ouro/card/card";

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

Example

<Card title="Pantry" description="What you have on hand" action={<Button variant="plain">Edit</Button>}>
  <Text>Flour, rice, black beans.</Text>
</Card>
<Card
  href="/cookbooks/weeknight"
  media={<AspectRatio ratio={4 / 3}><img src={cover} alt="" /></AspectRatio>}
  title="Weeknight dinners"
  description="12 recipes"
/>

Use instead when

  • Use Item instead for a compact row in a list (media, title, description and actions side by side), and Stack when the group needs no surface.

Props

Type: CardProps.

action
Type: ReactNode
One control beside the title, at the end: a menu or a share button. With href it stays its own tab stop, above the link.
as
Type: "div" | "article" | "li" | "section"
Default: "div"
The element to render: li in a list of cards, article for a self-contained item.
children
Type: ReactNode
The card's body, under the title.
className
Type: string
Layout only: margins, width, grid placement (col-span-2). Appearance classes warn in development; use variant.
description
Type: ReactNode
A sentence or a count under the title: "12 recipes".
external
Type: boolean
With href: opens the link in a new tab, safely, and tells screen readers so.
footer
Type: ReactNode
A row at the bottom for buttons or a timestamp. With href, controls here stay their own tab stops.
headingLevel
Type: 2 | 3 | 4 | 5 | 6
Default: 3
The title's heading level. Pick the level below the section the card sits in.
href
Type: string
Makes the whole card one link, with one tab stop, named by its title. Internal paths go through OuroProvider's linkComponent, as with Link. Controls in any slot (a share button over the media, a link in the body, a button in action or footer) stay their own tab stops and take their own clicks and taps.
linkRef
Type: Ref<HTMLAnchorElement>
With href: a ref to the link's <a>, to move focus to it (as a "Show more" does for the first new card).
media
Type: ReactNode
An image or video across the top, edge to edge: usually an AspectRatio around an <img>, so the card keeps its shape while the image loads.
ref
Type: Ref<HTMLElement>
Reaches the rendered element.
size
Type: "sm" | "md"
Default: "md"
Padding: md is 24px, sm 16px for dense grids.
stackBelow
Type: "sm" | "md"
Below this breakpoint the action drops under the title and description, as in a settings panel on a phone. Without it the action stays beside the title at every width.
title
Type: ReactNode
The card's title, as a heading. With href it is the link's text, so a linked card needs one.
variant
Type: "outline" | "plain"
Default: "outline"
outline is a bordered surface in the theme's card colors; plain has no frame or padding, for a card's structure inside a surface of your own.

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.

  • actions: Not a prop. Ouro UI uses action beside the title, or footer below the body.
  • asChild: Not a prop. With href the whole card is a link: <Card href="/recipes/1" title="…">.
  • header: Not a prop. The header is title, description and action.
  • image: Not a prop. Ouro UI uses media: <Card media={<AspectRatio ratio={4 / 3}><img … /></AspectRatio>}>.
  • subtitle: Not a prop. Ouro UI uses description: <Card description="12 recipes">.
  • to: Not a prop. Ouro UI uses href, for router links too: <Card href="/recipes/1" title="…">.

className is for layout only

Pass margins, width and grid placement (mt-4, w-full, col-span-2). Your classes always win over Ouro UI's: Card merges className last with cn (tailwind-merge), so a class that conflicts with its own replaces it.layout-classes

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.

Claim sources

Source on GitHubThis page as Markdown