GrSwitch

<GrSwitch v-model="notifications" name="notifications" value="on">
  Email notifications
</GrSwitch>

The semantics of a checkbox: a switch that is on sends name=value, and one that is off is not sent at all — the server tells “off” by the absence of the key. Without name there is no hidden field; form links the switch to a form if it lies outside it.

Interactive content inside a <button> is invalid, so the hidden field is a neighbour of the button, and the root of the component is a fragment. class and the other attributes still land on the button.

<GrSwitch :model-value="backup" :loading="syncing" @change="save" />

loading shows a spinner in the thumb, marks the control aria-busy and blocks toggling while the request is in flight. What exactly is loading is set by loadingText (the gr.switch.loading key by default): aria-busy on its own is not announced by some screen readers.

The label arrives through the default slot, and labelPosition="start" moves it to the left of the track. The row is unfolded rather than rearranged in the DOM: a screen reader reads the order of the nodes, and the track has to stay first.

Without a label the name has to be set another way — ariaLabel or a GrFormField, which will link a <label for> to the button.

<GrSwitch v-model="notifications" show-state-text>
  Notifications
</GrSwitch>

showStateText puts “on/off” inside the track, on the side free of the thumb: the state reads on its own, without a comparison with the neighbouring switch. The texts come from the locale (gr.switch.on / gr.switch.off) and are overridden by the checkedText / uncheckedText props.

The label is drawn only at md and lg; at xs and sm it is absent, and in the dev build the component explains why. It is a matter of geometry: beside the thumb there remain 13 / 17 / 21 / 29px at the xs…lg steps, while a three-letter word takes about 19px even at a 9px type size. The track does not stretch to fit the text in the process — its width is fixed by the size table, and the travel of the thumb is computed from the same table.

Hence the Russian default too, the two-letter “yes” / three-letter “no”: the Russian word for “off” takes 31px and does not fit at any step. Text of your own is worth measuring the same way — a long one is clipped silently.

For a screen reader the label does not exist at all (aria-hidden): the track lies inside the <button role="switch">, and the visible text would enter the accessible name — “Wi-Fi ON” instead of “Wi-Fi”, although the state is already announced through aria-checked.

The colour of the label is the -fg role of the fill it lies on. If you have given the track a colour of your own through activeBackgroundColor, set the colour of the text as well: the library will not compute the contrast on an arbitrary fill. Both hooks (the colour and the type size) are in ../tokens.md.

<GrSwitch v-model="autosave">
  <template #checked-icon>
    <IconCheck class="h-full w-full" />
  </template>
  <template #unchecked-icon>
    <IconX class="h-full w-full" />
  </template>
  Autosave
</GrSwitch>

The checked-icon and unchecked-icon slots put a sign on the thumb itself. The size is held by a wrapper on the size step, and the content stretches to it (h-full w-full) — the same device as in GrBadge and GrChip, and for the same reason: the scale of the sign has to follow the switch rather than the markup at the call site.

The slots are independent: if a sign is needed in the on state only, the second one is simply not passed.

The sign has every step available, including xs and sm, where the state label does not fit into the track: the sign shrinks without losing recognisability, unlike a three-letter word. Inside the thumb it is left 8 / 10 / 12 / 16px.

loading displaces the sign. The spinner and the sign occupy the same centre, and while the request is in flight, “the state is changing” matters more than “what it has become”.

The sign is decorative: the thumb is aria-hidden as a whole, and the screen reader takes the state from aria-checked. Meaning that exists nowhere else must not be put here.

The colour of the sign and of the spinner is shared, from --gr-switch-thumb-fg. It does not branch by state and does not dim in disabled: it is the track that is dimmed, while the thumb stays --gr-card in every state, and content that changed its colour would part ways with its own backing.

<GrSwitch v-model="access" show-state-text auto-width checked-text="Enabled" unchecked-text="Disabled">
  Access by link
</GrSwitch>

autoWidth lifts the limit on length: the size step becomes the lower bound of the width, and beyond it the track grows to fit the label. The height does not change in the process — only the row stretches.

The default stays fixed on purpose. A row of switches with different labels becomes ragged, and whoever laid out a column for the width of the step would get a skew — that is the consumer’s choice, not the default behaviour.

The width does not twitch on toggling, although “on” and “off” are almost never equal in width: an invisible copy of the opposite text is put into the same cell, and the width is set by the larger of the two.

In both modes the thumb travels without a single number that depends on the width: the pair left: calc(100% − gap) and translateX(-100%) computes percentages from different elements — the first from the track, the second from the thumb itself. Stretching therefore needs neither measurements nor a ResizeObserver, and the travel stays linear: both values animate together.

Unavailability is dimmed with a background rather than with opacity: transparency dilutes text tokens tuned to AA and drops the contrast of the label.

update:modelValue and change are emitted together. The instance gives away focus() and blur().

The keyboard is native: the control is a real <button>, so Space and Enter toggle it by the browser’s own means, and Tab walks it in the general order.

size is xs…lg and is read from GrConfigProvider (componentDefaults.GrSwitch.size). The colour of the track is set pointwise with the activeBackgroundColor / inactiveBackgroundColor props.