Cards

::card-group
:::card{title="Renderers" icon="lucide:rocket" to="/guide/renderers/"}
Render with HTML, Vue, React, or Svelte.
:::

:::card{title="Source on GitHub" icon="lucide:github" to="https://github.com/onmax/comark-ui" color="neutral"}
Read the code, or open an issue.
:::
::

::columns{cols="2"}
:::column
**Before**

One long page of options.
:::

:::column
**After**

Each option under its own heading.
:::
::

::card-group
:::card{title="Failing" color="error" variant="soft" icon="lucide:circle-x"}
`upload.test.ts` times out on files over 10 MB.
:::

:::card{title="Passing" color="success" variant="soft" icon="lucide:circle-check"}
Every other test passes.
:::
::

A link card is one link that covers the card, named after its title, so a click anywhere opens it and a screen reader hears one link, not a card's worth of text. Links in the card's own text still work.

::card-group
:::card{title="Guides" description="Start here." icon="lucide:book-open" to="/guides/"}
:::

:::card
#title
The `api` route

#default
Every option it takes.
:::
::

::card-group sets its cards in two columns, and in one when the group is narrower than 36rem, whatever the screen's width, so a group in a sidebar or a narrow column stacks too. A card works on its own too.

::columns{cols="3"}
First cell.

:::column
Second cell, with

two paragraphs.
:::

Third cell.
::

Each block directly inside is a cell, and :::column groups several blocks into one. cols is 1 to 6, 2 by default, and every row stacks into one column when the block is narrower than 36rem.

The plugin adds every problem to meta.issues, as Validation describes:

• href instead of to. The card still links, but Nuxt UI ignores href, so the issue says to write to.
• A to that runs a script, such as javascript:, which doesn't link.
• A color it doesn't know, which shows as primary.
• A cols outside 1 to 6, an empty ::columns, and an icon comark-icon can't draw.
• A prop ::card or ::columns doesn't read, such as link or columns, which is ignored.

Each issue names its block, by its title when it has one, and says how to fix it. Each one has its own rule in Doctor.

A card with to renders the way Nuxt UI renders it. An empty link, named by the card's title, stretches over the card, and the card's content follows it. A screen reader reads the card as one link, and its text stays selectable. Links inside it sit on top of the stretched one, so they open on their own.

Links to other sites open in a new tab with rel="noopener noreferrer" and an arrow in the corner. Set target="_self" to keep them in the tab.

cards() takes one option, iconResolver, when you use it alone. In comarkUi(), cards takes no options, since cards share the resolver built from the icon options, and cards: false turns them off.

comark-icon resolves a card's icon while parsing. By default icons come from the Iconify API. Pass the page's resolver so every plugin shares it:

import { createIcons } from "comark-icon";
import cards from "comark-cards/html";

const plugins = [cards({ iconResolver: createIcons() })];

The parse plugin replaces each card's attributes with the ones it renders from, puts its title in a card-title node, and wraps each cell of ::columns in a column node:

["card", { "color": "primary", "to": "/guide", "label": "Docs", "icon": { "src": "data:image/svg+xml,…" } },
  ["card-title", {}, "Docs"],
  "Read it."]

The plugin sets external when the link opens in a new tab. label is the link's name, which is the title's text or "Card link".

comark-ui brings comark-cards and registers it. To use it alone, install it:

pnpm add comark @comark/html comark-cards

Register the plugin and pass the renderer's components:

import { createHtmlRenderer } from "@comark/html";
import cards, { components } from "comark-cards/html";

const render = createHtmlRenderer({ plugins: [cards()], components });

For Vue, React, or Svelte, import from comark-cards/vue, comark-cards/react, or comark-cards/svelte. The components add the styles when they mount. When you render on a server, import comark-cards/style.css with your own styles so the page doesn't shift. Renderers covers using it with other plugins.

A card is a <div class="ccr" data-color="...">. A group is a <div class="ccr-group">, and columns are a <div class="ccr-columns" data-cols="..."> of <div class="ccr-column">.

Each color reads Nuxt UI's variable, such as --ui-primary, then its own default. Primary falls back to shadcn/ui's --primary, then to the foreground, so cards match the page's brand color, or stay neutral without one. Set --ccr-primary and the others on .ccr to change one.

Cards also read these shared tokens:

The rules sit in a comark CSS layer, so any plain rule of your own wins.