GUILD OF GLEKS UIv21.19.0

gog-radio-group

Radio Group

An options-driven radio control — the radio counterpart to Checkbox. It renders native <input type="radio">s sharing one group name, so mutual exclusivity and arrow-key navigation come from the browser rather than from roving-focus code.

Overview

Import the component and drop it into a template.

typescript
import { RadioGroupComponent } from '@guildofgleks/ui';

@Component({
  // ...
  imports: [RadioGroupComponent],
})

Basic usage — [(value)] holds the selected option's id:

Delivery
value: standard
<div>
  <gog-radio-group label="Delivery" [options]="options" [(value)]="delivery" />
  <code>value: {{ delivery() }}</code>
</div>

Examples

States

Empty, holding a value, a disabled group, and an error — each with Enterprise disabled on its own, so the option-level and the group-level disabled can be read side by side. A disabled group fades once, as a whole 21.15.0; before, its options faded twice.

Value unset
Value set
Disabled group
Error
Pick a plan
<!-- Enterprise is disabled on its own, through its option's disabled: true. -->
<gog-radio-group label="Value unset" [options]="plans" />
<gog-radio-group label="Value set" [options]="plans" value="pro" />
<!-- A disabled group fades once, as a whole — label and options together. -->
<gog-radio-group label="Disabled group" [options]="plans" value="pro" disabled />
<gog-radio-group label="Error" [options]="plans" errorMessage="Pick a plan" />

Sizes

Five steps. The circle, the dot and the labels scale from the --gog-control-checkbox-* lengths gog-checkbox reads too, so a radio and a checkbox of one size line up on a form.

xsm
sm
md
lg
slg
@for (size of sizes; track size) {
  <gog-radio-group
    [size]="size"
    [label]="size"
    orientation="horizontal"
    [options]="plans"
    value="pro"
  />
}

Orientation and full width

vertical by default; horizontal for two or three short options. fullWidth makes every option as wide as the group, so the whole line is the hit target — and in a horizontal group the options share the row in equal parts, wrapping only once the labels no longer fit 21.15.0. Before 21.15.0 that last group came out as a vertical list.

Vertical (default)
Horizontal
Vertical, fullWidth
Horizontal, fullWidth
<gog-radio-group label="Vertical (default)" [options]="plans" value="free" />
<gog-radio-group label="Horizontal" orientation="horizontal" [options]="plans" value="free" />
<!-- fullWidth: every option is as wide as the group, so the whole line is the hit target. -->
<gog-radio-group label="Vertical, fullWidth" [options]="plans" value="free" fullWidth />
<!-- Horizontal and fullWidth: the options share the row, and wrap only when they must. -->
<gog-radio-group
  label="Horizontal, fullWidth"
  orientation="horizontal"
  [options]="plans"
  value="free"
  fullWidth
/>

Option ids and long labels

The id is the value and keeps its type: the first group uses numbers and hands back a number. A long label wraps beside its circle rather than pushing it out of line.

Seats
value: 5 (number)
When offline
<!-- The id is the value, and keeps its type: numbers come back as numbers. -->
<div>
  <gog-radio-group label="Seats" [options]="seats" [(value)]="seatCount" />
  <code>value: {{ seatCount() }} ({{ typeOf(seatCount()) }})</code>
</div>

<!-- A long label wraps beside its circle rather than pushing it out of line. -->
<gog-radio-group label="When offline" [options]="offline" value="keep" />

No visible label

ariaLabel names the group when the surrounding UI already says what it is. With a label set it is ignored: the visible text names the group through aria-labelledby.

<!-- No visible label: ariaLabel names the group. With a label set, it is ignored. -->
<gog-radio-group ariaLabel="Plan" orientation="horizontal" [options]="plans" value="pro" />

Two-way binding

value is a model. A press on the selected option changes nothing — a radio group cannot be emptied by the user, only by writing null to it. The second button writes the disabled option's id, and the group shows it selected: disabled on an option stops the user choosing it, not the model holding it. A value that matches no option selects nothing and is kept as it is.

Plan
value: pro · 0 valueChange
<div>
  <gog-radio-group
    label="Plan"
    [options]="plans"
    [(value)]="plan"
    (valueChange)="changes.update((n) => n + 1)"
  />
  <div>
    <!-- The user cannot empty a radio group; only the model can. -->
    <gog-button variant="outline" size="sm" (gogClick)="plan.set(null)">
      value.set(null)
    </gog-button>
    <!-- disabled stops the user choosing an option, not the model holding it. -->
    <gog-button variant="outline" size="sm" (gogClick)="plan.set('enterprise')">
      value.set('enterprise')
    </gog-button>
  </div>
  <code>value: {{ plan() ?? 'null' }} · {{ changes() }} valueChange</code>
</div>

Reactive forms and validation

A ControlValueAccessor. With errorDisplay="auto" the message appears once the control is invalid and touched — tab into the group and out again without choosing — and a choice clears it. Before 21.15.0 this mode never showed anything on a radio group 21.15.0: it was the one control that did not read the form's state back.

Plan (required)
value: null · touched: false · disabled: false
<div>
  <!-- Tab in and out without choosing: errorDisplay="auto" shows the error, a choice clears it. -->
  <gog-radio-group
    label="Plan (required)"
    [options]="plans"
    [formControl]="control"
    errorMessage="Pick a plan"
    errorDisplay="auto"
  />
  <div>
    <gog-button variant="outline" size="sm" (gogClick)="control.markAsTouched()">
      markAsTouched()
    </gog-button>
    <gog-button variant="outline" size="sm" (gogClick)="control.reset()">reset()</gog-button>
    <gog-button variant="outline" size="sm" (gogClick)="toggleDisabled()">
      {{ control.disabled ? 'enable()' : 'disable()' }}
    </gog-button>
  </div>
  <code>
    value: {{ control.value ?? 'null' }} · touched: {{ control.touched }} · disabled:
    {{ control.disabled }}
  </code>
</div>

App-wide defaults — GOG_CONFIG

control.size sets the default size; control.errorDisplay reaches this component too, so an app that wants every control on 'auto' sets it once. An instance's own input still wins. See Global Configuration.

Size from the config (lg)
size="sm" — the instance wins
<gog-radio-group label="Size from the config (lg)" [options]="plans" value="pro" />
<gog-radio-group label='size="sm" — the instance wins' size="sm" [options]="plans" value="pro" />

Options — your own objects

By default each option is a GogRadioOption, and value holds the selected option's id rather than the object itself, since a radio group is a single-value control bound straight to a form field.

typescript
interface GogRadioOption {
  id: string | number;
  label: string;
  disabled?: boolean;
}

optionLabel, optionValue and optionDisabled21.19.0 read any other shape, as on every other collection control (Select, Multiselect, Autocomplete, Button Toggle): each is a property path — dot-paths included — or a function. Their defaults are 'label', 'id' and 'disabled', which is the shape above, so a list that already has it needs none of them. optionValue must give a string or a number, because that is what value holds; there is no [optionValue]="null" to bind whole objects, as Select has.

Plan
value: team
Ship to
<!-- Your own objects: a property path for the label, functions for the value and disabled. -->
<div>
  <gog-radio-group
    label="Plan"
    [options]="plans"
    optionLabel="title"
    [optionValue]="planCode"
    [optionDisabled]="isRetired"
    [(value)]="plan"
  />
  <code>value: {{ plan() }}</code>
</div>

<!-- A dot-path reaches into a nested object. -->
<gog-radio-group label="Ship to" [options]="addresses" optionLabel="place.city" optionValue="key" />

Accessibility

A role="radiogroup" container around native radios sharing one name: the group carries the name and the error, and each option's role, state and keyboard come from the platform — there is no roving-focus code here.

  • Keyboard — the group is one tab stop; the arrows move and select, skipping disabled options.
  • Name — the visible label through aria-labelledby, or ariaLabel when there is none. Each option is a <label> around its input, so its text is its name.
  • Error — aria-invalid on the group and an aria-describedby pointing at the message.
  • name — unset, every group generates its own, which keeps two groups apart. Set it only for a native form submission, and never give two groups the same one: the browser would treat their options as one group behind both components' backs.

API Reference

Inputs

NameTypeDefaultDescription
optionsreadonly TOption[][]The choices, rendered as native <input type="radio">s. GogRadioOption ({ id, label, disabled? }) by default; any other shape through the three accessors below.
optionLabel21.19.0string | ((o: TOption) => string)'label'How an option turns into its visible text: a property path (dot-paths included, "place.city") or a function.
optionValue21.19.0string | ((o: TOption) => string | number)'id'What value holds for an option: a property path or a function. It must give a string or a number, as value does.
optionDisabled21.19.0string | ((o: TOption) => boolean)'disabled'Which options are disabled: a property path or a function.
valuestring | number | nullnullWhat optionValue gives for the selected option — its id by default. Two-way bindable with [(value)].
labelstring''The group’s own label, rendered above the options.
ariaLabelstring''Accessible name for the group, used when there is no visible label.
namestringauto-generatedThe shared name attribute for the radios. Generated per instance unless you set it — it is what makes the browser enforce mutual exclusivity.
orientation'vertical' | 'horizontal''vertical'How the options are laid out.
size'xsm' | 'sm' | 'md' | 'lg' | 'slg'GOG_CONFIG.control.size ?? 'md'Circle and label scale. Reuses gog-checkbox’s size steps.
disabledbooleanfalseDisables the whole group. Individual options carry their own optional disabled flag.
errorMessagestring''Validation message rendered under the group.
errorDisplay'manual' | 'auto'GOG_CONFIG.control.errorDisplay ?? 'manual'manual shows errorMessage whenever it is set; auto derives it from the bound form control’s state.
fullWidthbooleanfalseStretches the group to fill its container. Horizontal, the options share the width in equal parts, each pressable across its whole part, and still wrap once the labels no longer fit; before 21.15.0 a full-width horizontal group stacked its options.

Outputs

NamePayloadDescription
valueChangestring | number | nullEmitted when the selection changes. Comes from the value model input.

Global Configuration

Set any of these once with provideGogConfig() instead of repeating them on every instance — an instance's own input still wins when it sets one itself. See Global Configuration for the full reference.

  • GOG_CONFIG.control.size
  • GOG_CONFIG.control.errorDisplay

Styling Tokens

Every CSS custom property the radio group paints with. Override any of them — on a single instance, a subtree, or a theme — to restyle it. See the Theming guide for the full token-layering model, or the Theme Generator to tweak these live.

TokenDescription
--gog-radio-bg / -border-color / -border-width / -border-styleThe circle, unchecked.
--gog-radio-checked-bg / -checked-border / -dot-color / -dot-size-ratioThe circle and its dot once checked.
--gog-radio-label-color / -label-line-height / -gapPer-option label and the gap to its circle.
--gog-radio-group-label-color / -group-label-size / -group-label-font-family / -group-label-font-weight / -group-label-line-height / -group-label-letter-spacing / -group-label-text-transform / -group-gapThe group’s own label, and its gap to the options. Since 21.15.0 it aliases --gog-field-label-*, so it wears the same colour and font as every other field label — the accent in most themes, where it used to be the muted grey.
--gog-radio-group-option-gap / -group-option-gap-horizontalGap between options, vertical and horizontal orientation respectively.
--gog-radio-focus-ring / -focus-ring-width / -focus-ring-offsetKeyboard focus ring. The colour reads --gog-accent-color rather than the pale wash it used to, corrected in 21.12.0: this outline is the only thing marking focus on this control, and a wash measured 1.38:1 against the light page where WCAG asks for 3:1.
--gog-radio-error-color / -error-font-size / -disabled-opacityValidation error message and the disabled state.