Card component overview
bq-card does not enforce an internal layout. You decide how to structure the content inside — this flexibility supports everything from simple text blocks to rich data displays with icons, metrics, and actions.When to use
Use cards when
- You want to present concise information, actions, or collections of related content in a visually organized and scannable format
- You need to highlight featured details, related content, or navigation options in a contained surface
- The design benefits from a structured layout that helps users scan and compare grouped content
Do not use cards when
- You are presenting a single piece of information that does not need additional structure or supporting elements
- The content is a deeply interactive workflow — a form, a wizard, or a data table — where a card would act as a passive wrapper around something that deserves its own full-page context
- The design calls for a more fluid and continuous display instead of separated content blocks
Card patterns
The Card pattern can support multiple presentation styles depending on the content you’re presenting.Mini card
A compact layout for tight spaces — ideal for quick stats, summaries, or navigation links where a full-size card would feel heavy.
Card list
Multiple cards of the same type arranged in a grid or column — works well for scannable collections like articles, products, or team members.
Card with title and description
A structured card with a heading and supporting text — use when the card needs to explain something or guide users toward a next step.
Anatomy
Cards are flexible containers, so their anatomy can vary depending on the content. In most cases, a card includes a container, an optional visual element, a content area, and optional supporting actions.
Card component anatomy
Design guidelines
Alignment
Typography
Establish a clear hierarchy inside each card by following this order:1
Primary value
Bold or larger text for the headline — a title, metric, or name. This is what users read first.
2
Supporting detail
Secondary-weight or muted text for context — a description, timestamp, or label.
3
Action
A brand-colored link or button at the bottom. Keep it to one primary action per card.
States
bq-card has no built-in hover, active, or focus visual feedback — it is a static container by design. Interactive children such as buttons and links carry their own state styles. When a whole card represents a navigable destination, wrap it in a semantic <a> element rather than relying on a click handler on the card surface (see Accessibility for details).Usage
The examples below show the most common card layouts, each with a live preview and code for HTML, React, Angular, and Vue.Default content
A card with icon, title, description, and a call-to-action — use when users need context before deciding to act.Card list
Use a card list when you have a collection of items that share the same structure — product catalogs, article feeds, team directories. The repeated layout helps users scan and compare entries quickly without having to re-learn the pattern on each card.Performance overview
A KPI card combining an icon, headline value, and trend indicator — ideal for analytics dashboards and executive reports.Mini card
A compact horizontal card usingtype="minimal" that removes built-in padding, letting you create visually distinct inner zones — like the branded left panel shown here.
Options
Types
type is a layout decision that controls whether the card applies its own internal padding or leaves spacing entirely up to you.
Border radius
Use theborder property to control the card corner radius.
Best practices
DoKeep cards within the same group visually consistent — same size, same internal layout — so users can scan and compare them quickly.
Don’tMix unrelated card layouts in the same group when users are expected to compare items — inconsistency makes scanning harder.
DoLimit each card to one primary topic or action. If a card is trying to do too much, consider splitting the content or using a dedicated page.
Don’tOverload a card with long descriptions or multiple unrelated actions — if the content needs more room, a dedicated page or panel is a better fit.
DoLead with the most important information. Place the primary value — a number, a name, or a status — at the top so users see it at a glance before reading further.
Don’tNest cards inside other cards. It creates visual confusion and makes hierarchy hard to follow — use a different layout pattern instead.
DoChoose icons that match the card’s content — a wallet for finance, a chart for analytics. Users should be able to identify the card’s purpose from the icon at a glance.
Don’tUse icons as pure decoration. An icon that has no connection to the card’s content adds visual noise without adding meaning.
Accessibility
- Images — provide descriptive
alttext for any images inside a card so screen readers can convey what the image shows. - Headings — use a proper heading hierarchy within the card so assistive technologies can navigate the content structure correctly.
- Keyboard navigation — ensure all interactive elements inside a card (buttons, links) are reachable and operable with the keyboard alone.
- Color contrast — maintain sufficient contrast between the card background, text, and UI elements so content remains readable for all users.
Navigation
When a card represents a link destination (for example, an article or product), wrap it in a semantic<a> element. bq-card is a non-interactive container and does not handle click or keyboard events on its own.
API reference
Properties
Slots
Shadow parts
CSS custom properties
Resources
Interactive playground
Explore card configurations in Storybook
Source code
View the component source on GitHub