Skip to content
CraftDocs
GitHub
Home
Home
Changelog
What's New
Guide
Guide
Getting Started
Principles
Styling Components
Theme System
Foundations
All Tokens
Color
Elevation
Icons
Motion
Shape
Spacing
Typography
Libraries
Libraries
@xds/cli
@xds/core
Themes
Themes
Theme: daily
Default Theme
Theme: matcha
Neutral Theme
Components
Components
AppShell
AspectRatio
Avatar
Avatar
AvatarStatusDot
Badge
Banner
Breadcrumbs
BreadcrumbItem
Breadcrumbs
Button
Button
IconButton
ToggleButton
ToggleButtonGroup
Calendar
Card
Carousel
Chat
ChatComposer
ChatComposerDrawer
ChatComposerInput
ChatComposerTokenElement
ChatDictationButton
ChatLayout
ChatLayoutScrollButton
ChatMessage
ChatMessageBubble
ChatMessageList
ChatMessageMetadata
ChatSendButton
ChatSystemMessage
ChatTokenizedText
ChatToolCalls
Checkbox
CheckboxInput
CheckboxList
CheckboxListItem
ClickableCard
Code
CodeBlock
Collapsible
Collapsible
CollapsibleGroup
useXDSCollapsible
CommandPalette
CommandPalette
CommandPaletteEmpty
CommandPaletteFooter
CommandPaletteGroup
CommandPaletteInput
CommandPaletteItem
CommandPaletteList
DateInput
Dialog
AlertDialog
Dialog
DialogHeader
useXDSImperativeAlertDialog
useXDSImperativeDialog
Divider
DropdownMenu
DropdownMenu
DropdownMenuDivider
DropdownMenuItem
DropdownMenuItemData
DropdownMenuSection
EmptyState
Field
Field
FieldLabel
FieldStatus
Heading
HoverCard
Icon
Kbd
Layout
Center
FormLayout
Grid
GridSpan
HStack
Layout
LayoutContainer
LayoutContent
LayoutFooter
LayoutHeader
LayoutPanel
Section
StackItem
VStack
Link
List
List
ListItem
Markdown
MetadataList
MetadataList
MetadataListItem
MobileNav
MoreMenu
NavHeadingMenu
NavIcon
NumberInput
OverflowList
Pagination
Popover
PowerSearch
ProgressBar
Radio
RadioList
RadioListItem
Resizable
ResizeHandle
useXDSResizable
SegmentedControl
SegmentedControl
SegmentedControlItem
SelectableCard
Selector
MultiSelector
Selector
SelectorOption
SideNav
SideNav
SideNavCollapseButton
SideNavHeading
SideNavItem
SideNavSection
Skeleton
Slider
Spinner
StatusDot
Switch
Table
BaseTable
Table
TableCell
TableHeaderCell
TableRow
useXDSTableColumnSettings
useXDSTablePagination
useXDSTableSelection
useXDSTableSelectionState
useXDSTableSortable
Tabs
Tab
TabList
TabMenu
Text
TextArea
TextInput
Thumbnail
TimeInput
Timestamp
Toast
Toast
useXDSToast
Token
Tokenizer
Toolbar
Tooltip
TopNav
TopNav
TopNavHeading
TopNavItem
TopNavMegaMenu
TopNavMegaMenuFeaturedCard
TopNavMegaMenuItem
TopNavMenu
TreeList
Typeahead
BaseTypeahead
Typeahead
TypeaheadItem
useXDSHoverCard
useXDSPopover
useXDSTooltip
Utilities
Utilities
LinkProvider
MediaTheme
SyntaxTheme
Theme
useClickableContainer
useEntryAnimation
useFocusTrap
useGridFocus
useImageMode
useInputContainer
useListFocus
useMediaQuery
useOverflow
useScrollLock
useScrollOverflow
useXDSLayer
useXDSStreamingText
Terms of UsePrivacy Policy
Type to search
↑↓Navigate↵SelectEscClose
Card@xds/core · XDSCard v0.0.13

Usage

Card groups related content into a visually distinct container with a border and background. Use it for profile cards, settings panels, data summaries, or any content that needs to stand out from the page.
ts
import {XDSCard} from '@xds/core/Card'

Best practices

GuidancePractices
DoTry a section first — only use a card when you need the visual separation of a border and elevated background.
DoKeep padding consistent across sibling cards so they align visually in a grid or list.
DoUse the muted variant for secondary content like tips, callouts, or background information.
DoPair a card with XDSLayout when you need a structured header, scrollable content, and footer with actions.
Don'tNest cards inside other cards — flatten the hierarchy or use a section instead.
Don'tUse color variants for status — use Banner or Badge for that. Color cards are for categorization.

Examples

Common configurations, variations, and states.
Card — Callout
tsx
'use client';
​
import {XDSCard} from '@xds/core/Card';
import {XDSStack} from '@xds/core/Layout';
import {XDSHeading, XDSText} from '@xds/core/Text';
​
export default function CardCallout() {
return (
<XDSStack direction="horizontal" gap={4}>
<XDSCard width={270} variant="muted">
<XDSStack direction="vertical" gap={2}>
<XDSHeading level={3}>Tip</XDSHeading>
<XDSText type="body" color="secondary">
Use the muted variant for callouts or supplementary information.
</XDSText>
</XDSStack>
</XDSCard>
<XDSCard width={270} variant="muted">
<XDSStack direction="vertical" gap={2}>
<XDSHeading level={3}>Note</XDSHeading>
<XDSText type="body" color="secondary">
Muted cards work well in sidebars or help panels.
</XDSText>
</XDSStack>
</XDSCard>
</XDSStack>
);
}
Card — Layout
tsx
'use client';
​
import {XDSCard} from '@xds/core/Card';
import {
XDSLayout,
XDSLayoutHeader,
XDSLayoutContent,
XDSLayoutFooter,
XDSHStack,
} from '@xds/core/Layout';
import {XDSButton} from '@xds/core/Button';
import {XDSHeading, XDSText} from '@xds/core/Text';
​
export default function CardWithInnerLayout() {
return (
<XDSCard width={380}>
<XDSLayout
header={
<XDSLayoutHeader hasDivider>
<XDSHeading level={3}>Edit Profile</XDSHeading>
</XDSLayoutHeader>
}
content={
<XDSLayoutContent>
<XDSText type="body" color="secondary">
Update your display name, bio, and profile photo. Changes are
saved immediately.
</XDSText>
</XDSLayoutContent>
}
footer={
<XDSLayoutFooter hasDivider>
<XDSHStack gap={2} hAlign="end">
<XDSButton label="Cancel" variant="ghost" />
<XDSButton label="Save changes" variant="primary" />
</XDSHStack>
</XDSLayoutFooter>
}
/>
</XDSCard>
);
}
Card — Simple
tsx
'use client';
​
import {XDSCard} from '@xds/core/Card';
import {XDSStack} from '@xds/core/Layout';
import {XDSHeading, XDSText} from '@xds/core/Text';
​
export default function CardWithSimpleContent() {
return (
<XDSCard width={360}>
<XDSStack direction="vertical" gap={2}>
<XDSHeading level={3}>Project Overview</XDSHeading>
<XDSText type="body" color="secondary">
This project tracks the redesign of the onboarding flow. The goal is
to reduce drop-off by 15% in Q2.
</XDSText>
<XDSText type="supporting" color="secondary">
Last updated 2 hours ago
</XDSText>
</XDSStack>
</XDSCard>
);
}
Card — Variants
tsx
'use client';
​
import {XDSCard} from '@xds/core/Card';
import {XDSStack} from '@xds/core/Layout';
import {XDSText} from '@xds/core/Text';
​
const VARIANTS = [
{variant: 'default' as const, label: 'General', note: '4 tasks due today'},
{
variant: 'muted' as const,
label: 'Archived',
note: 'No activity in 30 days',
},
{variant: 'blue' as const, label: 'Engineering', note: '12 open issues'},
{variant: 'green' as const, label: 'Marketing', note: '3 campaigns active'},
{variant: 'orange' as const, label: 'Urgent', note: '2 items need review'},
{variant: 'purple' as const, label: 'Design', note: '5 drafts in progress'},
];
​
export default function CardVariants() {
return (
<XDSStack direction="horizontal" gap={3} style={{flexWrap: 'wrap'}}>
{VARIANTS.map(({variant, label, note}) => (
<XDSCard key={variant} variant={variant} width={160}>
<XDSStack direction="vertical" gap={1}>
<XDSText type="body" weight="bold">
{label}
</XDSText>
<XDSText type="supporting" color="secondary">
{note}
</XDSText>
</XDSStack>
</XDSCard>
))}
</XDSStack>
);
}
ClickableCardWithNestedButtonA product card that navigates on click but has an independent
tsx
'use client';
​
import {XDSClickableCard} from '@xds/core/ClickableCard';
import {XDSStack} from '@xds/core/Layout';
import {XDSText, XDSHeading} from '@xds/core/Text';
import {XDSButton} from '@xds/core/Button';
​
export default function ClickableCardWithNestedButton() {
return (
<XDSClickableCard label="Product" href="/product/123" width={320}>
<XDSStack direction="vertical" gap={3}>
<XDSStack direction="vertical" gap={1}>
<XDSHeading level={4}>Wireless Headphones</XDSHeading>
<XDSText type="body" color="secondary">
$79.99
</XDSText>
</XDSStack>
<XDSButton label="Add to cart" onClick={() => {}} variant="primary" />
</XDSStack>
</XDSClickableCard>
);
}
SelectableCardMultiMulti-select tag picker using color variant selectable cards with color-matched selection borders.
tsx
'use client';
​
import {useState} from 'react';
import {XDSSelectableCard} from '@xds/core/SelectableCard';
import {XDSStack} from '@xds/core/Layout';
import {XDSText} from '@xds/core/Text';
​
const tags = [
{id: 'react', name: 'React', variant: 'blue' as const},
{id: 'typescript', name: 'TypeScript', variant: 'cyan' as const},
{id: 'node', name: 'Node.js', variant: 'green' as const},
{id: 'python', name: 'Python', variant: 'yellow' as const},
{id: 'rust', name: 'Rust', variant: 'orange' as const},
{id: 'go', name: 'Go', variant: 'teal' as const},
];
​
export default function SelectableCardMulti() {
const [selected, setSelected] = useState(new Set(['react', 'typescript']));
​
return (
<XDSStack direction="horizontal" gap={2} wrap="wrap">
{tags.map(tag => (
<XDSSelectableCard
key={tag.id}
label={tag.name}
isSelected={selected.has(tag.id)}
variant={tag.variant}
onChange={isNow => {
setSelected(prev => {
const next = new Set(prev);
if (isNow) {
next.add(tag.id);
} else {
next.delete(tag.id);
}
return next;
});
}}
width={130}>
<XDSText type="body" weight="bold">
{tag.name}
</XDSText>
</XDSSelectableCard>
))}
</XDSStack>
);
}

Showcase source

tsx
'use client';
​
import {XDSCard} from '@xds/core/Card';
import {XDSStack} from '@xds/core/Layout';
import {XDSText, XDSHeading} from '@xds/core/Text';
​
export default function CardShowcase() {
return (
<XDSCard width={320}>
<XDSStack direction="vertical" gap={2}>
<XDSHeading level={4}>Card title</XDSHeading>
<XDSText type="body" color="secondary">
Cards group related content with a border and background. Use them for
profiles, settings panels, or data summaries.
</XDSText>
</XDSStack>
</XDSCard>
);
}