Vaulthalla Logo

Cards

Use card grids and individual cards for overview pages, feature lists, and related links.

Cards

Use :::cards for card grids and :::card for individual cards.

1:::cards{2  columns="3"3  theme="spacious"4  cardTheme="glass"5}6 7:::card[Markdown Field]{8  eyebrow="Core"9  href="/getting-started/fields-and-blocks"10}11Portable Markdown content.12:::13 14:::card[Cyan Card]{15  eyebrow="Custom"16  theme="cyan"17}18Overrides parent `cardTheme`.19:::20 21:::

:::cards

Attributes:

  • columns: 1, 2, 3, 4, or auto
  • href: optional link applied according to linkScope
  • linkScope: section, card, or title
  • newTab: open href in a new tab when true
  • theme: cards container theme
  • cardTheme: default child card theme

Defaults:

  • columns="3"
  • linkScope="section"
  • newTab="false"
  • theme="default"

Invalid columns fall back to 3 and produce a non-fatal diagnostic where diagnostics are available.

Cards-level href, linkScope, and newTab can provide defaults for child cards. Supported linkScope values are:

  • section: one overlay link covers the whole cards section; child card link overrides are ignored
  • card: child cards inherit the parent href as full-card links unless they override it
  • title: child card titles inherit the parent href unless a child card overrides it

:::card

Attributes:

  • [Label]: optional card title, preferred for new Markdown
  • title: optional card title retained for existing Markdown
  • eyebrow: optional small label above the title
  • icon: local icon reference such as @fa-duotone/bolt
  • href: optional card link
  • linkScope: full or title
  • newTab: open href in a new tab when true
  • theme: card theme

Cards support nested Markdown and render safely inside or outside a :::cards container.

Use expanded attributes and [Label] for new content:

1:::card[Fast Setup]{2  icon="@fa-duotone/bolt"3  theme="glass"4}5Install, configure, ship.6:::

Existing title="" content remains valid. If [Label] and title are both present, [Label] is used. Differing values produce a non-fatal diagnostic.

Parent And Child Themes

cardTheme on :::cards applies to child cards that do not set their own theme:

1:::cards{2  columns="2"3  cardTheme="glass"4}5 6:::card[Inherits Glass]7Content.8:::9 10:::card[Overrides Parent]{theme="cyan"}11Content.12:::13 14:::

When href is present on :::cards, linkScope="section" is the default. The whole cards section becomes one link:

1:::cards{href="/getting-started/fields-and-blocks"}2 3:::card[Markdown Field]4Portable Markdown content.5:::6 7:::card[Rendering]8Server-rendered output.9:::10 11:::

Section-scoped links do not support child card link overrides. Set linkScope="card" when each child card should inherit the parent link as a full-card link:

1:::cards{2  href="/getting-started/fields-and-blocks"3  linkScope="card"4}5 6:::card[Markdown Field]7Portable Markdown content.8:::9 10:::card[Custom Target]{href="/directives/cards"}11This card overrides the parent `href`.12:::13 14:::

Set linkScope="title" on :::cards when child card titles should inherit the parent link:

1:::cards{2  href="/getting-started/fields-and-blocks"3  linkScope="title"4}5 6:::card[Markdown Field]7Portable Markdown content.8:::9 10:::

Child cards can override card-level defaults:

1:::cards{2  columns="3"3  href="/docs"4  linkScope="title"5}6 7:::card[Install]8Install the plugin.9:::10 11:::card[Configure]12Configure the editor and renderer.13:::14 15:::card[Customize]{16  href="/configuration/directive-themes"17  linkScope="full"18}19This card overrides the parent default and links the full card.20:::21 22:::

When href is present on an individual :::card, the whole card is clickable by default:

1:::card[Markdown Field]{href="/getting-started/fields-and-blocks"}2Portable Markdown content.3:::

Set linkScope="title" on :::card to keep the link on the title only:

1:::card[Markdown Field]{2  href="/getting-started/fields-and-blocks"3  linkScope="title"4}5Portable Markdown content.6:::

Set newTab or newTab="true" on :::cards or :::card to open links in a new tab. Child cards can override a parent value with newTab="false":

1:::card[External Guide]{2  href="https://example.com"3  linkScope="full"4  newTab=true5}6Portable Markdown content.7:::

Full-card links should not contain nested buttons or other links. Use linkScope="title" when the card body contains links:

1:::card[Read the Docs]{2  href="/docs"3  linkScope="title"4  icon="@fa-duotone/book-open"5}6Only the card title is linked. This keeps buttons and other links in the card body valid.7:::

CTA Composition

A dedicated CTA directive is not required for common calls to action. Compose a :::card with :::buttons, and keep the card link scoped to the title when the body contains buttons:

1:::card[Ready to build better docs?]{2  href="/docs"3  icon="@fa-duotone/rocket"4  linkScope="title"5}6Use rich Markdown directives, icon packs, buttons, cards, and clean autocomplete without turning docs into a page builder.7 8:::buttons{9  align="center"10  stack="mobile"11  gap="md"12}13::button[Get Started]{14  href="/docs"15  variant="primary"16  icon="@fa-duotone/book-open"17}18 19::button[View GitHub]{20  href="https://github.com/valkyrianlabs/payload-markdown"21  variant="secondary"22  icon="@brand/github"23  newTab=true24}25:::26 27:::

Dense Grids

Use columns="auto" when cards have uneven lengths or the viewport width is unpredictable:

1:::cards{2  columns="auto"3  cardTheme="muted"4}5 6:::card[Short]7Small note.8:::9 10:::card[Longer]11Longer content can wrap without forcing every card into a rigid column.12:::13 14:::

Themes

Built-in card themes:

  • default
  • muted
  • glass
  • cyan
  • violet
  • emerald
  • amber
  • danger

Built-in cards container themes:

  • default
  • compact
  • spacious
  • feature-grid