Radio Group
FreeRadio group with default, card and button-group styles. ControlValueAccessor for reactive forms.
</>sv-radio-group radioformselection
import { SvRadioGroupComponent } from '@styloviz/forms';Demo & usage
Basic usage
Usage example — open the gallery for the full interactive demo.
An interactive demo for this component lives in the gallery.
Open live demoMore examples
Selectable cards
Render options as cards with descriptions for richer choices.
example.htmlAngular
1 lines
<sv-radio-group radioStyle="card" [options]="plans" groupLabel="Plan" [(value)]="plan" />
Required + validation
required adds aria-required and a "*"; errorMessage sets aria-invalid and is linked via aria-describedby. Also works with formControlName.
example.htmlAngular
7 lines
<sv-radio-group formControlName="size" radioStyle="button" groupLabel="Size" [options]="sizes" [required]="true" [errorMessage]="form.controls.size.invalid ? 'Pick a size' : ''" />
When to use
- Picking exactly one option from a small, visible set (2–6 choices).
- You want all options visible at once for easy comparison.
- For longer lists collapse to a Select Dropdown; for instant toggles use a Toggle.
Async states
None — this component has nothing to load, so it has no loading, empty or error state to drive.
Inputs
| Name | Type | Default | Description |
|---|---|---|---|
| value | string (two-way) | '' | Currently selected value. Use `[(value)]` for two-way binding. |
| options | RadioOption[] | [] | Array of radio options to render. |
| layout | RadioGroupLayout | 'vertical' | Layout direction. |
| radioStyle | RadioGroupStyle | 'default' | Visual style. |
| size | RadioGroupSize | 'md' | Size of each radio item. |
| variant | RadioGroupVariant | 'primary' | Active color variant. |
| disabled | boolean | false | Disable all options. |
| required | boolean | false | Mark the group as required (sets `aria-required`). |
| groupLabel | string | '' | Optional legend/label for the group. |
| ariaLabel | string | '' | `aria-label` for the group — use when there is no visible `groupLabel`. |
| hint | string | '' | Helper text shown below the group (hidden when `errorMessage` is set). |
| errorMessage | string | '' | Error message shown below the group; sets `aria-invalid` when present. |
| serverError | string | { readonly message: string } | null | null | A validation failure reported by the **server** — the 422 that comes back after submit, not something the client could have known. It is a separate input from `errorMessage` because it has a different lifetime, not because it needs a second way to show a string. A server error is a statement about *the value that was submitted*: the moment the user edits the field it stops being true, and this input expires itself rather than sitting there telling someone their new email is already taken. `errorMessage` has no such expiry — it is the host's to clear. While live it outranks `errorMessage`: it is the more specific fact, and it is the one the user has not seen yet. Typed structurally rather than as `SvDataError` so this stays dependency free — an `SvDataError` satisfies it unchanged. |
| groupName | string | '' | Explicit `name` for the radio inputs. Auto-generated when omitted. |
| customClass | string | '' | Additional CSS classes on the root wrapper. |
Outputs
| Event | Payload type | Description |
|---|---|---|
| changed | string | Emits the newly selected value. |
| valueChange | string | Emits the new `value` whenever it changes — the output half of `[(value)]`. |
Customization & theming
- Render as classic radios, selectable cards, or a segmented button group via `radioStyle`; choose `layout` (vertical, horizontal, grid), `size` and `variant`.
- Provide `options` with `label`, `description`, `disabled` and `icon` (an icon-library name); name the group with `groupLabel` / `ariaLabel` and add `hint` / `errorMessage`.
- Two-way bind with `[(value)]` or a reactive control; mark `required`; listen to `(changed)` for the new value.
- Swatch variant for size / colour selection: colour dots or labelled chips, with per-option `color` and `soldOut` (non-interactive strike overlay).
Best practices
- Do: Always provide a `groupLabel` (or `ariaLabel`) describing what the choice represents.
- Do: Pre-select a sensible default so the group is never in an empty state.
- Don't: Don't use radios for multi-select — that's a Checkbox group.
Accessibility
- A real `role="radiogroup"` named via `aria-labelledby` (groupLabel) or `aria-label`; arrow keys and Home/End move between options and update the value in every style.
- Default and card styles use focusable native `<input type="radio">` (visually hidden) with a clear focus ring; the button style is a single tab stop with roving focus.
- Selected option exposes `aria-checked`; `required` sets `aria-required`, and `errorMessage` sets `aria-invalid` with the message linked via `aria-describedby`.
- Implements ControlValueAccessor — works with template & reactive forms; `formControl.disable()` disables the group.
Feedback on Radio Group
Spotted a gap in this page, or something that didn't work as described? Comments are GitHub Discussions in the public styloviz/community repo, so posting needs a GitHub account.