# Card ## Summary `Card` is a surface container for grouped content such as settings panels, dashboard blocks, and inline summaries. It is a layout and grouping surface, not a feedback or status primitive. ## Imports ```tsx import { Card, type CardProps, type CardSize, type CardAppearance, } from '@vega-ui/react'; ``` ## Exported Types - `CardProps` - `CardSize` - `CardAppearance` ## Basic Usage ```tsx import { Button, Card, Heading, Text } from '@vega-ui/react'; const features = ['Up to 25 members', '100 GB of storage', 'Priority email support', 'SAML single sign-on']; export default function BasicUsage() { return ( Team $12 per member / month ); } ``` ## Variants - Sizes: `sm`, `md`, `lg` - Appearances: `outline`, `transparent` - Composition: default `article` or `asChild` ## Edge Cases - `Card` is a layout surface, not a semantic replacement for headings or sections. - Transparent cards work only when the parent surface already provides contrast. - Internal spacing still belongs to child layout decisions. - If the UI is trying to communicate status or urgency rather than grouping content, `Alert` or `Badge` is usually the clearer abstraction. ## Common Mistakes - Expecting `Card` to provide all internal layout spacing automatically. - Using transparent cards on visually noisy backgrounds. - Encoding hierarchy only through card appearance. ## Examples ### Basic #### Basic: pricing plan `Card` renders an `article`, named by its heading through `aria-labelledby`. Content stacks in a column; spacing between children comes from `gap` on the card. ```tsx import { Button, Card, Heading, Text } from '@vega-ui/react'; const features = ['Up to 25 members', '100 GB of storage', 'Priority email support', 'SAML single sign-on']; export default function BasicUsage() { return ( Team $12 per member / month ); } ``` #### Basic: whole card as a link With `asChild` the card styles move onto an ``, so the entire surface is one link with one accessible name. Keep the content of a link card non-interactive: no buttons or nested links inside. ```tsx import { Card, Heading, Text } from '@vega-ui/react'; import './examples.css'; const destinations = [ { href: '#billing', title: 'Billing', description: 'Plan, invoices and payment methods.' }, { href: '#members', title: 'Members', description: '18 members, 3 pending invitations.' }, { href: '#security', title: 'Security', description: 'Two-factor authentication, sessions and SSO.' }, ]; export default function LinkCards() { return ( ); } ``` ### Controlled/Stateful #### Controlled/Stateful: metric card with refresh The value, the timestamp and the loading flag live in state. While refreshing, the card is `aria-busy`, the spinner has its own accessible name and the button is disabled. ```tsx import { useState } from 'react'; import { Button, Card, Heading, Spinner, Text } from '@vega-ui/react'; const formatter = new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }); export default function MetricsCard() { const [revenue, setRevenue] = useState(48210.4); const [updatedAt, setUpdatedAt] = useState('09:00'); const [loading, setLoading] = useState(false); const refresh = () => { setLoading(true); setTimeout(() => { const now = new Date(); setRevenue((current) => current + Math.round(Math.random() * 90000) / 100); setUpdatedAt(now.toLocaleTimeString('en-US', { hour: '2-digit', minute: '2-digit', hour12: false })); setLoading(false); }, 900); }; return ( Revenue this month
{formatter.format(revenue)} {loading && }
Updated at {updatedAt} ); } ``` ### Form/Integration #### Form/Integration: the card is the form `asChild` renders the card as a `
`, named by its heading. Values are read with `FormData` on submit, native `required` and `pattern` validate the fields, and reset clears the status message. ```tsx import { FormEvent, useState } from 'react'; import { Button, Card, Heading, Label, Text, TextField, TextFieldInput } from '@vega-ui/react'; export default function SettingsFormCard() { const [saved, setSaved] = useState(''); const submit = (event: FormEvent) => { event.preventDefault(); const data = new FormData(event.currentTarget); setSaved(`Saved “${data.get('workspace')}” at ${data.get('slug')}.vega.app`); }; return ( setSaved('')}>
Workspace Shown in invitations and in the browser tab.
{saved}
); } ``` ### Layout/Overlay #### Layout/Overlay: responsive grid with aligned actions `auto-fill` with `minmax(min(220px, 100%), 1fr)` gives as many columns as fit without overflowing on phones. Grid rows stretch the cards to equal height, and `margin-block-start: auto` keeps every button at the bottom regardless of text length. ```tsx import { Button, Card, Heading, Text } from '@vega-ui/react'; const integrations = [ { id: 'slack', name: 'Slack', description: 'Post deployment and incident updates to channels.' }, { id: 'github', name: 'GitHub', description: 'Link pull requests to releases and show build status on every commit, including drafts and forks.' }, { id: 'pagerduty', name: 'PagerDuty Incident Response Orchestration', description: 'Page the on-call engineer.' }, ]; export default function ResponsiveGrid() { return (
{integrations.map((integration) => ( {integration.name} {integration.description} ))}
); } ``` ### Error #### Error: data failed to load The card keeps its heading and explains the failure in a `role='alert'` region with a retry action. The retry shows a loading state before the data appears. ```tsx import { useState } from 'react'; import { Button, Card, Heading, Spinner, Text } from '@vega-ui/react'; type State = 'failed' | 'loading' | 'loaded'; export default function LoadErrorCard() { const [state, setState] = useState('failed'); const retry = () => { setState('loading'); setTimeout(() => setState('loaded'), 900); }; return ( API usage {state === 'loading' && } {state === 'failed' && (
Usage could not be loaded: the metrics service timed out.
)} {state === 'loaded' && ( 1.82 M of 2 M requests used this month )} ); } ``` ### Disabled #### Disabled: read-only details for non-owners `Card` has no disabled state of its own. A `
` inside it disables every field at once, and the explanation is linked with `aria-describedby`. ```tsx import { Card, Heading, Label, Text, TextField, TextFieldInput } from '@vega-ui/react'; export default function ReadOnlyBilling() { return (
Billing contact Only workspace owners can change billing details. Ask Maria Chen to update them.
); } ``` ### Edge #### Edge: empty state and hundreds of items The same card handles zero and 240 items. The empty state explains what to do next; the long list scrolls inside the card, and the scroll area is focusable and named so keyboard users can scroll it. ```tsx import { useState } from 'react'; import { Button, Card, Heading, Text } from '@vega-ui/react'; const allKeys = Array.from({ length: 240 }, (_, index) => `sk_live_${String(index + 1).padStart(4, '0')}`); export default function EmptyAndMany() { const [keys, setKeys] = useState([]); const toggle = () => { if (keys.length === 0) { setKeys(allKeys); return; } setKeys([]); }; return (
API keys ({keys.length})
{keys.length === 0 && ( No API keys yet. Create one to call the API from your servers. )} {keys.length > 0 && (
    {keys.map((key) => (
  • {key}
    • ))}
)} ); } ``` ## Anatomy ### Overview `Card` is a single grouped surface container with no public child parts. Its anatomy is one root surface plus whatever heading, body, metrics, or actions the consumer places inside. ### Required Parts #### `Card` Required. Owns surface appearance, padding, and optional polymorphic rendering through `asChild`. ### Optional Parts `Card` does not expose public child parts. ### Composition Order 1. `Card` 2. heading, text, actions, or layout children ### Valid Composition Patterns ```tsx import { Button, Card, Heading, Text } from '@vega-ui/react'; const features = ['Up to 25 members', '100 GB of storage', 'Priority email support', 'SAML single sign-on']; export default function BasicUsage() { return ( Team $12 per member / month
    {features.map((feature) => (
  • {feature}
    • ))}
); } ``` ### Invalid Composition Patterns #### Card used as the only semantic structure The surface should not replace headings, landmarks, or real content hierarchy. #### Transparent card on a low-contrast background The grouped content can lose visual separation entirely.