Card

When to useLink to "When to use"

• surface (default): a raised panel for settings sections, dashboard tiles, plan options.
• outline: border only, for lower emphasis or crowded layouts.
• soft: a tone-tinted fill to highlight a state (info, warning).
• href / onClick: the whole card is one target, such as a plan picker or a list of destinations.

Use something else when:

• the card holds its own buttons, links or inputs: use a static Card (no href/onClick) and put those controls inside
• you only need spacing between items: Stack or Inline

UsageLink to "Usage"

import { Card } from "@arshad-shah/cynosure";

<Card variant="outline" padding="lg" as="section">…</Card>
<Card href="/settings">Whole card is one link</Card>
<Card onClick={choose}>Whole card is one button</Card>
<Card variant="soft" tone="info">Heads up</Card>
<Card edge="success">Water the garden <Badge tone="success">Home</Badge></Card>
<Card as="section" title="Connection" description="Where the client connects.">…</Card>

Title and descriptionLink to "Title and description"

title and description put a header above the content; headingLevel (default 3) fits the title into the page outline. In a static or link card the title is a heading, and a section, article or aside card is named by it. A button may not hold a heading, so in a button card the title is plain text that still names the button.

With actions the header shares its row with them: the title wraps before the actions instead of running under them, on static cards and on link and button cards, where the actions stay outside the card's one target.

PaddingLink to "Padding"

padding is none, sm, md (default) or lg, and uses space tokens.

Coloured edgeLink to "Coloured edge"

edge draws a coloured edge on the card's inline-start side: the left in left-to-right text, the right in right-to-left. A tone name (accent, neutral, danger, success, warning, info) uses that tone's colour. Any other string is a CSS colour, for categories with their own colours.

The edge is the card's own start border, so it follows the card's radius, and the content starts after it. It works with every variant and tone, on link and button cards and with actions, and it keeps its colour when the card is hovered or focused.

Colour must not be the only carrier of meaning. Some people cannot tell the colours apart and a screen reader does not announce them. Say the same thing in the card's text or with a Badge, as the cards above do.

Interactive cardsLink to "Interactive cards"

With href the card renders as a link; unsafe URL schemes are not linked. With onClick it renders as a button and supports disabled. Keep the content non-interactive: one card, one target. When a card is interactive, as is ignored.

PropsLink to "Props"

Behaviour and accessibilityLink to "Behaviour and accessibility"

• Static cards: choose the element with as (div, section, article, li, aside).
• Names: a section, article or aside card with a title is named by it. Otherwise add aria-label when the card's content doesn't give a clear name.
• Ref: the ref points at the rendered element.
• Edge: edge is visual only and adds no element or name. In forced colours it stays as a thicker edge in the system text colour.

ThemingLink to "Theming"

Tokens: --cy-card-bg, --cy-card-border, --cy-card-radius, --cy-card-shadow and --cy-card-soft-mix.

createTheme({ components: { card: { radius: "12px", shadow: "none", edgeWidth: "6px" } } });

className and style are for layout only.

RelatedLink to "Related"

Badge · Stack · Inline · Link · Button