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.
| Part | Element | Description |
|---|---|---|
| 1 | Container | The outer surface that groups the content into a single, scannable unit |
| 2 | Visual | An optional icon, image, or highlight area that helps users identify the card content quickly |
| 3 | Content area | The main body containing the title, description, metrics, or supporting text |
| 4 | Actions | Optional buttons or links used when the card includes follow-up actions |
Design guidelines
Alignment
Typography
Establish a clear hierarchy inside each card by following this order:Primary value
Bold or larger text for the headline — a title, metric, or name. This is what users read first.
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.
| Type | Padding | When to use |
|---|---|---|
| default | Built-in (var(--bq-spacing-l)) | Most cards — content sits comfortably inside without extra wrapper elements |
| minimal | None | When you need full control over inner layout, such as a branded color block flush with the card edge |
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
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
border | border | The corner radius of the card component | 'none' | 'xs2' | 'xs' | 's' | 'm' | 'l' | 'full' | 'm' |
type | type | Type of card component | 'default' | 'minimal' | 'default' |
Slots
| Slot | Description |
|---|---|
| (default) | The content of the card component |
Shadow parts
| Part | Description |
|---|---|
wrapper | The wrapper container <div> of the element inside the shadow DOM |
CSS custom properties
Resources
Interactive playground
Explore card configurations in Storybook
Source code
View the component source on GitHub