ItemCard

ItemCard and CardGrid for catalogs.

Preview

getting-started

Create a documentation site in a few minutes.

Read

design-tokens

One file drives every color, radius and font.

Read

deploying

Publish to GitHub Pages with a publish check.

Read

src/examples/item-card/example.astro

---
import { CardGrid, ItemCard } from "@/presentation/components/site/item-card";
---

<CardGrid>
  <ItemCard
    href="#"
    title="getting-started"
    description="Create a documentation site in a few minutes."
    hint="Read"
  />
  <ItemCard
    href="#"
    title="design-tokens"
    description="One file drives every color, radius and font."
    hint="Read"
  />
  <ItemCard
    href="#"
    title="deploying"
    description="Publish to GitHub Pages with a publish check."
    hint="Read"
  />
</CardGrid>

Add to your site

npx docs-sitekit add item-card

It writes these files, and keeps a file you changed:

src/presentation/components/site/item-card.tsx

It requires these entries of the registry, which add restores first:

Props

Built from the TypeScript types and the TSDoc comments of the component, so they cannot drift from the code.

Props of ItemCard
Key	Type	Default	Allowed values	Description
`href`	string	required	-	Where the card leads. The whole card is the link.
`title`	string	required	-	The title, in mono type.
`description`	string	required	-	A sentence under the title. An empty text leaves the paragraph out.
`badge`	string	-	-	The text of a badge over the title.
`tone`	Tone	"neutral"	"neutral", "brand", "success", "warn"	The tone of the badge.
`hint`	string	-	-	A short text at the foot of the card, before the arrow.

Props of CardGrid
Key	Type	Default	Allowed values	Description
`children`	string \| number \| bigint \| boolean \| React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| Iterable<React.ReactNode> \| React.ReactPortal \| Promise<AwaitedReactNode>	required	-	The cards of the grid.
`className`	string	-	-	Classes added to the grid.

Variants and states

With a badge

A tone badge over the title, to say what kind of page the card leads to.

Start

upgrading

Bring a site up to date.

Read

src/examples/item-card/badge.astro

---
import { CardGrid, ItemCard } from "@/presentation/components/site/item-card";
---

<CardGrid>
  <ItemCard href="#" title="getting-started" description="Create a site." badge="Start" tone="brand" hint="Read" />
  <ItemCard href="#" title="deploying" description="Publish to GitHub Pages." badge="Ship" tone="success" hint="Read" />
  <ItemCard href="#" title="upgrading" description="Bring a site up to date." badge="Care" tone="warn" hint="Read" />
</CardGrid>

Title and description only

Without a badge or a hint, the card is a title, a text and an arrow.

basic

The smallest example.

src/examples/item-card/plain.astro

---
import { CardGrid, ItemCard } from "@/presentation/components/site/item-card";
---

<CardGrid>
  <ItemCard href="#" title="basic" description="The smallest example." />
</CardGrid>

About

A link card for a catalog: an optional badge, a title in mono type, a description and a hint, in a CardGrid that has explicit tracks so columns line up. Any other attribute of a link, such as the data- attributes that CatalogFilter reads, goes to the link.

Accessibility

The whole card is one link, so a screen reader reads the badge, the title, the description and the hint as the name of the link.
The arrow is aria-hidden.
The title is an h3, so put the grid under a heading of level 2.
The grid is one column on a phone, two from md and three from lg, and a card never needs a sideways scroll.

Source

item-card.tsx

Edit this page

Last updated 5 November 2026