Selection card
A selection card is a larger option with room for a description, an icon, or a price. The whole card is the click target; the tk-radio or tk-checkbox inside it does the selecting.
<tk-radio-group label="Choose your plan" name="plan" value="starter">
<tk-selection-card>
<tk-icon slot="media" name="user"></tk-icon>
<tk-radio slot="control" value="starter" helper="For one person, $9 a month">Starter</tk-radio>
<span slot="meta">$9/mo</span>
</tk-selection-card>
<tk-selection-card>
<tk-icon slot="media" name="star"></tk-icon>
<tk-radio slot="control" value="pro" helper="For growing teams, $29 a month">Pro</tk-radio>
<span slot="meta">$29/mo</span>
</tk-selection-card>
</tk-radio-group>Anatomy
| Part | What it is |
|---|---|
tk-selection-card |
the bordered card; the whole card is one click target |
control slot |
a tk-radio or tk-checkbox, required. Its label is the card title and the accessible name; its helper is the description |
media slot |
an optional icon or image before the title; screen readers skip it |
meta slot |
an optional price or badge after the title; screen readers skip it |
The control you put in decides the mode: a circle means pick one, a square means pick any. Don't mix the two in one group.
Checkbox cards
<tk-checkbox-group label="Add features">
<tk-selection-card>
<tk-checkbox slot="control" name="features" value="analytics" helper="Dashboards and exports">Analytics</tk-checkbox>
</tk-selection-card>
<tk-selection-card>
<tk-checkbox slot="control" name="features" value="backups" helper="Daily, kept for 30 days" checked>Backups</tk-checkbox>
</tk-selection-card>
</tk-checkbox-group>Each checkbox card is its own Tab stop and submits its checkbox's name and value. Radio
cards share the group's one Tab stop and its value.
Control position
control-position="trailing" puts the control at the end, after the title. The default,
leading, puts it first. media always comes first and meta always last.
<tk-radio-group label="Shipping" name="shipping" value="standard">
<tk-selection-card control-position="trailing">
<tk-radio slot="control" value="standard" helper="3 to 5 business days">Standard</tk-radio>
</tk-selection-card>
<tk-selection-card control-position="trailing">
<tk-radio slot="control" value="express" helper="Next business day">Express</tk-radio>
</tk-selection-card>
</tk-radio-group>States
<tk-radio-group label="Account type" name="account" value="personal">
<tk-selection-card>
<tk-radio slot="control" value="personal">Personal</tk-radio>
</tk-selection-card>
<tk-selection-card disabled>
<tk-radio slot="control" value="business" helper="Not available in your region">Business</tk-radio>
</tk-selection-card>
</tk-radio-group>On hover, the border gets stronger and the card tints. Keyboard focus on the control shows one ring around the whole card.
- Selected: a stronger border and a tint, plus the control's own check or dot. Set it
on the control (
checked) or the group (value), never on the card. disabled: disables the control and dims the card. A disabled group dims its cards too. Say why in the description, or leave the option out.- Error and required: set them on the group. The message shows above the cards, and the cards don't change color.
When to use
- Use selection cards when each option needs more than one line: a description, an icon, a price.
- Put a
tk-radioinside to pick exactly one, with the cards in aRadio group . - Put a
tk-checkboxinside to pick any number, with related cards in aCheckbox group . - Use a plain radio or checkbox for one-line options.
- Use a
Select orCombobox for a long list. - Don't put a
Switch in a card. Lay switches out as settings rows.
Content
- Write the title as the control's label: name the option, short, in sentence case, with no end punctuation. On a checkbox card, a selected card turns the thing on.
- Write the description in the control's
helper: one short sentence, no full stop, no links. - Keep
metato a price or a short tag. Screen readers skip it, so repeat a value that defines the choice, such as the price, in the title or description. - Make the group label the question or the category, in one sentence.
Do / Don't
| ✅ Do | ❌ Don't |
|---|---|
Put a tk-radio in for one choice, a tk-checkbox for many |
Mix radio and checkbox cards in one group |
| Write the title in the control's label | Add a separate title and leave the control unnamed |
| Let the whole card be the target | Put a link or a button inside a card |
| Put error and required on the group | Color a card for a group error |
| Use a plain radio or checkbox for one-line options | Wrap every small option in a card |
| Lay a switch out as a settings row | Put a switch in a card |
Related
Radio group : the control for radio cards, and its group.Checkbox : the control for checkbox cards, and its group.Switch : an on/off setting; lay it out as a row, not a card.
API
Attributes
| Attribute | Type | Default | What it does |
|---|---|---|---|
control-position |
leading | trailing |
leading |
puts the control first or last |
disabled |
boolean | false |
disables the control and dims the card |
Slots
| Slot | Content |
|---|---|
control |
one tk-radio or tk-checkbox, required |
media |
an optional icon or image before the title |
meta |
an optional price or badge after the title |
Events
No events of its own. Listen for change on the checkbox, or on the radio group.
CSS
::part(card): the card surface, the click target.
Tokens
| State | Border | Surface |
|---|---|---|
| rest | border/subtle |
surface/default |
| hover | border/strong |
state/hover |
| selected | border/selected |
state/on; hover state/on-hover |
| disabled | border/disabled |
surface/disabled |
The focus ring is border/accent/focus. The title, description, and check use the control's
own tokens. The card has radius-12 corners and space-16 padding and gaps. Values per
theme:
Accessibility
Built in:
- The control inside does the work: its label names the card, its group gives the keyboard and the form value, and screen readers hear a plain radio or checkbox.
- A click anywhere on the card selects the control once.
- One focus ring around the whole card, never hidden.
- Selection shows without color: the control's check or dot and the card's border.
Your part:
- Put the title in the control's label and the description in its
helper. - Don't put a link or a button inside a card; the whole card is one target.
- Set error and required on the group, never on a card.
| Control | Keyboard |
|---|---|
| checkbox card | Tab reaches each card; Space checks or unchecks it |
| radio card | Tab enters the group; the arrow keys move between cards and select; Space selects |
Contrast limits
- Resting border: 1.33:1 in light and 2.00:1 in dark, under the 3:1 minimum; 4.22:1 in high contrast. The hover border is 1.86:1 in light. The control's own circle or box and its label still mark each option.
- Selected border: at least 8.17:1 in every theme.