Containers that use borders, drop shadows, or background colors to indicate grouping are commonly referred to as cards. This document provides examples of how to create various card style layouts using the surface component.
Containers that use a card style layout, whether they are just bordered boxes, use drop shadows to indicate elevation, or use background colors to indicate grouping, are a common pattern in designs. This pattern is often used to group related information together, and can be used to create a visual hierarchy on a page.
Reach for this pattern when the user picks one item from a homogeneous collection (accounts, cards, payees). Wrap the set in a bordered q2-surface so the grouping reads as a related set instead of blurring into the page. Make each q2-item clickable — the whole row is the tap target, which matters most on mobile. Use q2-avatar on the left as a scannable identifier and q2-detail in the body so label/value pairs align vertically across rows. Prefer this over a table when the row has 2–4 pieces of data — tables are for dense comparison; grouped lists are for selection.
<q2-surface background="default" border="default" radius="2">
<q2-list bordered label="Accounts">
<q2-item clickable>
<q2-avatar slot="decorator" icon="bank"></q2-avatar>
<div slot="header">Checking Account</div>
<q2-detail label="Account Number" description="xxxx-xxx-0745" slot="body"></q2-detail>
<q2-detail label="Current Balance" slot="body">
<q2-currency amount="12953.25"></q2-currency>
</q2-detail>
</q2-item>
<q2-item clickable>
<q2-avatar slot="decorator" icon="bank"></q2-avatar>
<div slot="header">Checking Account</div>
<q2-detail label="Account Number" description="xxxx-xxx-0745" slot="body"></q2-detail>
<q2-detail label="Current Balance" slot="body">
<q2-currency amount="12953.25"></q2-currency>
</q2-detail>
</q2-item>
<q2-item clickable>
<q2-avatar slot="decorator" icon="bank"></q2-avatar>
<div slot="header">Checking Account</div>
<q2-detail label="Account Number" description="xxxx-xxx-0745" slot="body"></q2-detail>
<q2-detail label="Current Balance" slot="body">
<q2-currency amount="12953.25"></q2-currency>
</q2-detail>
</q2-item>
</q2-list>
</q2-surface>Reach for this pattern when a form is one of several things on a page (an address block on a profile page, a preferences panel on settings). The q2-surface isolates the form as a discrete task with a clear start and end. Use inset="normal" so labels and hints have room, border="default" with radius="2" to draw the boundary, and elevation="1" to signal "this is the thing to interact with." Put the heading inside the surface so the group carries its own label. For address blocks, use a columns="6" grid so full-width fields (line 1) and thirds (city/state/ZIP) coexist without switching grid systems mid-form.
<q2-surface background="default" inset="normal" border="default" radius="2" elevation="1">
<h2>Address</h2>
<q2-form>
<q2-grid columns="6">
<q2-grid-area column-span="6">
<q2-input label="Address 1"></q2-input>
</q2-grid-area>
<q2-grid-area column-span="6">
<q2-input label="Address 2" optional></q2-input>
</q2-grid-area>
<q2-grid-area column-span="6" md-column-span="2">
<q2-input label="City"></q2-input>
</q2-grid-area>
<q2-grid-area column-span="6" md-column-span="2">
<q2-select label="State">
<q2-option value="AL" display="Alabama">Alabama</q2-option>
<q2-option value="AK" display="Alaska">Alaska</q2-option>
<q2-option value="AZ" display="Arizona">Arizona</q2-option>
</q2-select>
</q2-grid-area>
<q2-grid-area column-span="6" md-column-span="2">
<q2-input label="Postal code" type="postal"></q2-input>
</q2-grid-area>
</q2-grid>
</q2-form>
</q2-surface>Reach for this pattern for at-a-glance summary tiles (spending rollups, KPIs, period comparisons). Use q2-surface background="secondary" instead of a bordered card so the tinted fill separates the tile without competing with the value. Use inset="compact" — dense tiles keep the row side-by-side. Set the grid's column count to match the number of stats (3 for week/month/year, 4 for quarters); a responsive count creates orphan rows and defeats the purpose of side-by-side comparison. q2-detail with stacked puts labels above values so tiles align on the row the eye scans first. Prefer this over a chart when 2–4 exact values matter; use a chart when the shape of the change matters more.
<q2-grid columns="3" gap="comfortable" align="start">
<q2-grid-area>
<q2-surface background="secondary" inset="compact" radius="1">
<q2-detail label="Last 24 hours" size="small" stacked>
<q2-currency amount="2948.95"></q2-currency>
</q2-detail>
</q2-surface>
</q2-grid-area>
<q2-grid-area>
<q2-surface background="secondary" inset="compact" radius="1">
<q2-detail label="Last 7 days" size="small" stacked>
<q2-currency amount="25049.13"></q2-currency>
</q2-detail>
</q2-surface>
</q2-grid-area>
<q2-grid-area>
<q2-surface background="secondary" inset="compact" radius="1">
<q2-detail label="Last 30 days" size="small" stacked>
<q2-currency amount="70501.12"></q2-currency>
</q2-detail>
</q2-surface>
</q2-grid-area>
</q2-grid>Reach for this pattern when promoting a single high-value action the user wasn't already pursuing (enrollment, upgrade, feature signup). This is the one container where visual weight is intentional: border="primary" with border-gradient catches the eye, and inset="comfortable" gives the CTA room to read as important rather than crowded. Use an image-left, text-right grid — the shape reads as "here's an offer, here's why, here's how to take it." Always pair the primary action with a lower-commitment secondary ("Learn more") in a q2-action-group; a solo primary feels pushy and earns fewer clicks. One CTA per page — multiple loud cards cancel each other out.
You shouldn't have to pay for accesss to your money, and when you bank with us, you won't have to. With our industry-leading savings rates, you'll actually make money when you save.
<q2-surface background="default" border="primary" border-gradient inset="comfortable" radius="1">
<q2-grid columns="3" align="center" justify="center">
<q2-grid-area column-span="3" md-column-span="1">
<q2-icon type="pricetag" style="--tct-icon-size: 125px"></q2-icon>
</q2-grid-area>
<q2-grid-area column-span="3" md-column-span="2" align="center" justify="start">
<h2 style="margin-top: 0">Save big with us</h2>
<p>You shouldn't have to pay for accesss to your money, and when you bank with us, you won't have to. With our industry-leading savings rates, you'll actually <em>make</em> money when you save.</p>
<q2-action-group>
<q2-btn intent="workflow-primary" size="small">
<q2-icon type="play"></q2-icon>
<span>Get Started</span>
</q2-btn>
<q2-btn intent="workflow-secondary" size="small">
<q2-icon type="question"></q2-icon>
<span>Learn More</span>
</q2-btn>
</q2-action-group>
</q2-grid-area>
</q2-grid>
</q2-surface>