MDX components

Card

Props, examples, and layouts for the Card component in published docs pages

Overview

Card creates a linked tile with a title. You can add a subtitle, description, icon, or image. Use cards for navigation at the start or end of a section: related pages, next steps, feature groups, and external resources. Wrap one or more cards in CardGrid to lay them out as a grid.

Props

Prop	Type	Required	Description
`title`	string	Yes	The card heading.
`subtitle`	string	No	Short label shown with the card, such as `"Guide"`.
`description`	string	No	One or two sentences describing the destination.
`href`	string	No	Destination of the card. Use a page path such as `/mdx-components/note`, or an `https` address.
`icon`	string	No	Icon name, such as `"rocket"`, `"book"`, `"code"`, or `"settings"`. Any Lucide icon name works.
`image`	string	No	Image path or address for the `image` variant.
`variant`	string	No	`"normal"` (default), `"small"`, or `"image"`.
`external`	boolean	No	Set to `true` for links that leave the site.
`className`	string	No	Extra CSS classes for small spacing adjustments.

Icon names accept both camelCase (bookOpen) and kebab-case (book-open).

Basic example

jsx

<CardGrid>
  <Card
    subtitle="Guide"
    title="REST API"
    description="Browse the endpoints and send your first request."
    href="/rest-api/index"
  />
</CardGrid>

Variants

Variant	When to use it
`normal`	Default. A full card with subtitle, title, and description.
`small`	Compact navigation where many links appear together.
`image`	Cards that lead with a picture. Pass the picture in `image`.

jsx

<CardGrid>
  <Card
    title="Navigation"
    href="/site-settings-pages/navigation"
    icon="settings"
    variant="small"
    description="Set the sidebar structure and page order."
  />
</CardGrid>

Common layouts

Next steps at the end of a page

Place one card group at the end of a page so readers can continue to related topics.

jsx

<CardGrid>
  <Card
    title="Note"
    href="/mdx-components/note"
    description="Add callouts for requirements and warnings."
  />
  <Card
    title="Tabs"
    href="/mdx-components/tabs"
    description="Show per-language or per-platform examples."
  />
</CardGrid>

Mixing internal and external links

Set external={true} on links that leave the site. Internal page paths need no extra prop.

jsx

<CardGrid>
  <Card
    title="Overview"
    href="/overview"
    icon="rocket"
    description="Learn what Doxa does and how its parts fit together."
  />
  <Card
    title="Source code"
    href="https://github.com/acme/widget"
    icon="code"
    external={true}
  />
</CardGrid>

Compact link list

Use small cards with an icon for a dense set of links:

jsx

<CardGrid>
  <Card title="REST API" href="/rest-api/index" icon="book" variant="small" />
  <Card title="Navigation" href="/site-settings-pages/navigation" icon="settings" variant="small" />
  <Card title="Source code" href="https://github.com/acme/widget" icon="code" variant="small" external={true} />
</CardGrid>

Usage rules

Place CardGrid at the start or end of a section, not between paragraphs.
Do not put cards inside a Step or a Note.
Use className only for spacing. Positioning classes such as fixed, absolute, sticky, and offset or z-* utilities are removed when the page renders.
Keep each card's title short and put detail in description.

Related components:

Cards link to pages. To show content inline, use Note, Tabs, or Step.

PreviousAdvanced JSON NextNote