Skip to main content

Radio

Overview​

The Radio component provides a Bulma-styled radio button input with flexible labels and helper classes.

Use it for mutually exclusive choices in forms—either standalone or grouped (with the same name).


Import​

import { Radio, Radios, Control } from '@allxsmith/bestax-bulma';

Usage​

Mutually Exclusive Radios (Only One Can Be Selected)​

This example shows how to use the Radio component for mutually exclusive choices. Assign the same name prop to each Radio in a group to ensure only one can be selected at a time. Use within a Control for proper Bulma styling.

<Control>
  <Radio name="mutuallyExclusive"> Yes </Radio>
  <Radio name="mutuallyExclusive"> No </Radio>
  <Radio name="mutuallyExclusive"> Maybe </Radio>
</Control>


Default Selected Radio​

Set the defaultChecked prop on a Radio to make it selected by default. This is useful for pre-selecting a common or recommended option in a group.

<Control>
  <Radio name="pet"> Cat </Radio>
  <Radio name="pet" defaultChecked>
    {' '}
    Dog{' '}
  </Radio>
</Control>


Disabled Radios​

Use the disabled prop to render radios that cannot be selected. This is helpful for indicating unavailable options in a group.

<Control>
  <Radio name="response" disabled>
    {' '}
    Attend{' '}
  </Radio>
  <Radio name="response" disabled>
    {' '}
    Decline{' '}
  </Radio>
  <Radio name="response" disabled>
    {' '}
    Tentative{' '}
  </Radio>
</Control>


List of Radios (Grouped with the Radios Wrapper)​

Render a list of radios using the Radios wrapper component, which groups related radio buttons under one name, its own or one it generates. In this example, all radios are disabled.

<Radios>
  <Radio name="event" disabled>
    {' '}
    Attend{' '}
  </Radio>
  <Radio name="event" disabled>
    {' '}
    Decline{' '}
  </Radio>
  <Radio name="event" disabled>
    {' '}
    Tentative{' '}
  </Radio>
</Radios>


Valid Colors and Sizes​

The values color and size accept are exported as readonly tuples, radioColors and radioSizes. The prop types are built from them, so they hold the same values as the Props table below. Map over them to build a color or size picker, as the two groups below do, or check a value that arrives at runtime (from a CMS or a query string, say) before you pass it in: a value outside the tuple adds no modifier class. Import them from the package root. The valid value constants page covers the typing and validation idioms.

import { Radio, Radios } from '@allxsmith/bestax-bulma';
import { radioColors, radioSizes } from '@allxsmith/bestax-bulma';

function example() {
  return (
    <>
      <Radios label="Accent color" name="accent" defaultValue="primary">
        {radioColors.map(color => (
          <Radio key={color} value={color} color={color}>
            {color}
          </Radio>
        ))}
      </Radios>
      <Radios label="Size" name="accent-size" defaultValue="normal">
        {radioSizes.map(size => (
          <Radio key={size} value={size} size={size}>
            {size}
          </Radio>
        ))}
      </Radios>
    </>
  );
}

Circle Size​

The circle is --bulma-radio-size across, 1.25em by default, so it grows with the label's font size and the size prop. It doesn't go below 24px, whatever that variable says: the stylesheet gives the circle a min-width and min-height of 24px, the minimum size WCAG 2.2 sets for a target (2.5.8, Target Size (Minimum)), so a circle with no label text beside it is still easy to hit. With Bulma's default font sizes, 1.25em comes out under 24px at the default and small sizes, so those two circles are both 24px.

For a smaller circle, lower the floor along with the size, on a class you pass through className. Name .styled-radio beside your class in each selector, so the rules win whatever order the stylesheets load in, and use .bestax-styled-radio and .bestax-check under the prefixed flavor:

.styled-radio.compact-radio {
--bulma-radio-size: 20px;
}

.styled-radio.compact-radio .check {
min-width: 0;
min-height: 0;
}
<Radio name="plan" value="basic" className="compact-radio">
Basic
</Radio>

Keep the label text inside the Radio when you shrink the circle. The whole label is the click target, so it stays easy to hit when the circle alone is small.


Accessibility​

  • Each Radio is rendered as a <label> wrapping an <input type="radio"> and the label text, for optimal accessibility.
  • Radios that share a name are one group: only one can be checked, and the arrow keys move between them. Inside Radios they take the group's name, or one it generates when you give it none. Outside one, give each the same name.
  • The circle is at least 24px across, the minimum size WCAG 2.2 sets for a target (2.5.8), whatever --bulma-radio-size says. Circle Size shows how to make it smaller, and why to keep the label text inside the Radio when you do.
  • An unchecked radio shows only its ring, --bulma-radio-border-color. It defaults to --bulma-text-weak, which holds the 3:1 contrast WCAG asks of a control's boundary (non-text contrast) on Bulma's page and card surfaces in light and dark. Set a replacement on a class you pass through className, since style goes to the <input>, naming the label's class too (.styled-radio.my-radio) so load order can't undo it, and hold it to 3:1 as well.
  • In forced colors (Windows contrast themes), the circle and the dot take system colors. A disabled radio, its dot and its label draw in the system's color for disabled text there, at full strength rather than dimmed.


Additional Resources​


Props​

PropTypeDefaultDescription
color'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger'—Color of the radio button.
size'small' | 'normal' | 'medium' | 'large'—Size of the radio button.
textColorBulma color | 'inherit' | 'current'—Text color helper.
disabledbooleanfalseWhether the radio is disabled.
classNamestring—Additional CSS classes, on the outer <label>. That's the element that declares the --bulma-radio-* variables, so a class is how to set one: style and the other input attributes go to the <input>. Name .styled-radio beside your class in the selector, so it beats the label's own declaration whatever order the stylesheets load in. A color prop declares the active color again on .styled-radio.is-<color>, which ties that selector, so leave color unset when a class sets it.
childrenReact.ReactNode—The label/content for the radio.
refReact.Ref<HTMLInputElement>—Forwarded to the underlying element.
...All standard <input> attributes and Bulma helper props—Helper props go on the outer <label>, with className. The other attributes go on the <input>. See Helper Props

CSS & Sass Variables​

Radio registers these variables on its own .styled-radio element. Override them there (or via className) — a value set on an ancestor is only inherited, and loses to the component-level declaration. See Theme.

CSS VariableSass VariableDefault
--bulma-radio-size$radio-size1.25em
--bulma-radio-border-width$radio-border-width2px
--bulma-radio-border-color$radio-border-colorvar(--bulma-text-weak)
--bulma-radio-background$radio-backgroundtransparent
--bulma-radio-dot-color$radio-dot-colorvar(--bulma-radio-active-color)
--bulma-radio-active-color$radio-active-colorvar(--bulma-primary)
--bulma-radio-label-gap$radio-label-gap0.5em
--bulma-radio-focus-shadow-size$radio-focus-shadow-size0 0 0 0.125em
--bulma-radio-transition-duration$radio-transition-durationvar(--bulma-duration)

--bulma-radio-size has a floor: the circle doesn't render smaller than 24px, whatever the variable says. Circle Size says why, and how to go below it.

Focus shadow size: --bulma-radio-focus-shadow-size ($radio-focus-shadow-size) is registered, and nothing reads it, so setting it changes nothing. The keyboard focus ring is a 2px outline in --bulma-radio-active-color, with no shadow for a size to apply to. It stays registered so a Sass build that configures it keeps compiling.