AisRadioGroup

AisRadioGroup provides a container and exposes options for controlling the layout of a group of AisRadio components. AisRadioGroup is intended to work hand-in-hand with Tailwind's flex and grid utilities.

Radio specification

A group's radio buttons may be specified either as an array (via the options prop), defined explicitly in the tag body, or both. This provides both a convenient and flexible solution regardless of the form or source of your data.

String options

The first method to populate a radio group is to bind the options prop to an array of strings.

Apple

Banana

Grape

Selection: Apple

<script setup>
  import { ref } from 'vue'
  import { AisRadioGroup } from '@ais-public/ais-components'

  const options = ref(['Apple', 'Banana', 'Grape'])
  const selection = ref('Apple')
</script>

<template>
  <div class="grid gap-4">
    <AisRadioGroup class="px-4"
        :options="options"
        v-model="selection"
    />
    <div class="p-4 bg-ui-gray-50 border rounded">
      Selection: {{ selection }}
    </div>
  </div>
</template>

Object options

The options prop will also accept structured data in the form of an array of objects. By default, the component will use the following field keys to populate each radio: label, value, icon, and disabled. You can point to more appropriate fields in your object using the props: labelKey, valueKey, iconKey, and disabledKey.

John

Paul

George

Ringo

Pete

Selection: george-harrison

<script setup>
import { ref } from 'vue'
import { AisRadioGroup } from '@ais-public/ais-components'

const options = ref([
  { label: 'John', value: 'john-lennon', icon: 'person', disabled: false },
  { label: 'Paul', value: 'paul-mccartney', icon: 'person', disabled: false },
  { label: 'George', value: 'george-harrison', icon: 'person', disabled: false },
  { label: 'Ringo', value: 'ringo-starr', icon: 'person', disabled: false },
  { label: 'Pete', value: 'pete-best', icon: 'person', disabled: true },
])
const selection = ref('george-harrison')
</script>

<template>
  <div class="grid gap-4">
    <AisRadioGroup
        class="px-4"
        :options="options"
        v-model="selection"
        labelKey="label"
    />
    <div class="p-4 bg-ui-gray-50 border rounded">
      Selection: {{ selection }}
    </div>
  </div>
</template>

Default slot

In lieu of passing options, developers may also explicitly define radio buttons in the body of the group. This is a good way to handle a small number of options that aren't pulled from a database. Note that the group's v-model will be applied to radio buttons defined in the slot.

All

Bringing It All Back Home

Highway 61 Revisited

Blonde on Blonde

Basement Tapes

Selection:

<script setup>
import { ref } from 'vue'
import { AisRadioGroup } from '@ais-public/ais-components'
import { AisRadio } from '@ais-public/ais-components'


const selection = ref('')
</script>

<template>
  <div class="grid gap-4">
    <AisRadioGroup v-model="selection" class="px-4">
      <AisRadio value="">All</AisRadio>
      <AisRadio value="biabh">Bringing It All Back Home</AisRadio>
      <AisRadio value="h61r">Highway 61 Revisited</AisRadio>
      <AisRadio value="BoB">Blonde on Blonde</AisRadio>
      <AisRadio value="basement">Basement Tapes</AisRadio>
    </AisRadioGroup>
    <div class="p-4 bg-ui-gray-50 border rounded">
      Selection: {{ selection }}
    </div>
  </div>
</template>

Head slot

Radio buttons generated by the options prop will appear before radio buttons defined in the group's body. However, the group also defines a slot named head that will place its contents before those of options.

Head 1

Head 2

Option 1

Option 2

Selection: Head 1

<script setup>
import { ref } from 'vue'
import { AisRadioGroup } from '@ais-public/ais-components'
import { AisRadio } from '@ais-public/ais-components'

const options = ref(['Option 1', 'Option 2'])
const selection = ref('Head 1')
</script>

<template>
  <div class="grid gap-4">
    <AisRadioGroup
      :options="options"
      v-model="selection"
      class="px-4"
    >
      <template #head>
        <AisRadio value="Head 1">Head 1</AisRadio>
        <AisRadio value="Head 2">Head 2</AisRadio>
      </template>
    </AisRadioGroup>
    <div class="p-4 bg-ui-gray-50 border rounded">
      Selection: {{ selection }}
    </div>
  </div>
</template>

Custom iteration

Taking explicit declarations a step further, you can also iterate over a set of options in the group's body. This is potentially useful in a number of situations. First off, it allows developers to group multiple collections of options. Secondly, it gives developers full control over the markup used for a radio, which could be useful for building a custom layout (e.g. adding a description field) or easing the calculation of display values.

JohnSinger, Guitar

PaulSinger, Bass

GeorgeGuitar

RingoDrums

Selection: Ringo

<script setup>
import { ref } from 'vue'
import { AisRadioGroup } from '@ais-public/ais-components'
import { AisRadio } from '@ais-public/ais-components'


const options = ref([
  { label: 'John', role: 'Singer, Guitar', icon: 'person' },
  { label: 'Paul', role: 'Singer, Bass', icon: 'person' },
  { label: 'George', role: 'Guitar', icon: 'person' },
  { label: 'Ringo', role: 'Drums', icon: 'person' },
])
const selection = ref('Ringo')
</script>

<template>
  <div class="grid gap-4">
    <AisRadioGroup
        class="px-4"
        valueKey="label"
    >
      <AisRadio
          v-for="option in options"
          :id="`ch-${option.label}`"
          v-model="selection"
          :value="option.label"
          :icon="option.icon"
      >
        <span class="flex flex-col gap-0 leading-tight pl-2">
          <span>{{ option.label }}</span>
          <span class="text-sm text-muted italic">
            {{ option.role }}
          </span>
        </span>
      </AisRadio>
    </AisRadioGroup>
    <div class="p-4 bg-ui-gray-50 border rounded">
      Selection: {{ selection }}
    </div>
  </div>
</template>

Radio layout

The layout of a radio group is controlled by three attributes: display, gap, and class. The three work together using Tailwind's flex and grid utilities to define a layout.

The default layout is defined as display="flex" class="flex-wrap" :gap=['gap-x-8', 'gap-y-4]. In English that means the radio buttons will expand horizontally with pleasant spacing. This layout works well for the typical case where we have a single row of radio buttons with the occasional new line.

display

The display prop sets the group's layout method. Accepted values are flex and grid. Developers can create a vertical listing of radio buttons by setting display to grid.

Apple

Banana

Grape

Selection: Banana

<script setup>
import { ref } from 'vue'
import { AisRadioGroup } from '@ais-public/ais-components'

const options = ref(['Apple', 'Banana', 'Grape'])
const selection = ref('Banana')
</script>

<template>
  <div class="grid gap-4">
    <AisRadioGroup
      display="grid"
      gap="gap-1"
      class="px-4"
      :options="options"
      v-model="selection"
    />
    <div class="p-4 bg-ui-gray-50 border rounded">
      Selection: {{ selection }}
    </div>
  </div>
</template>

gap

The gap prop sets the group's spacing. gap takes a string or an array of Tailwind gap utilities. See Tailwind's documentation for details. Tweaking the group's spacing is an easy first customization.

Apple

Banana

Grape

Selection: Banana

<script setup>
import { ref } from 'vue'
import { AisRadioGroup } from '@ais-public/ais-components'

const options = ref(['Apple', 'Banana', 'Grape'])
const selection = ref('Banana')
</script>

<template>
  <div class="grid gap-4">
    <AisRadioGroup
        gap="gap-x-24"
        class="px-4"
        :options="options"
        v-model="selection"
    />
    <div class="p-4 bg-ui-gray-50 border rounded">
      Selection: {{ selection }}
    </div>
  </div>
</template>

class

Developers can use the group's class attribute to customize the layout with more Tailwind utilities. For instance, if the group is set to grid, then grid-cols-4 can be included in the class attribute to specify a 4-column grid.

Apple

Banana

Grape

Strawberry

Kiwi

Pomegranate

Orange

Pear

Peach

Raspberry

Blueberry

Blackberry

Selection: Peach

<script setup>
  import { ref } from 'vue'
  import { AisRadioGroup } from '@ais-public/ais-components'

  const options = ref([
      'Apple', 'Banana', 'Grape', 'Strawberry',
      'Kiwi', 'Pomegranate', 'Orange', 'Pear',
      'Peach', 'Raspberry', 'Blueberry', 'Blackberry'
  ])
  const selection = ref('Peach')
</script>


<template>
  <div class="grid gap-8">
    <AisRadioGroup
        display="grid"
        :gap="['gap-x-6', 'gap-y-4']"
        class="grid-cols-4 p-4 "
        v-model="selection"
        :options="options"
    />

    <div class="p-4 bg-ui-gray-50 border rounded">
      Selection: {{ selection }}
    </div>
  </div>
</template>

Alternatively, Tailwind's flex-based justification utilities provide additional layout options that can be specified using class. Flex and grid techniques should be preferred to older methods such as floating elements.

justify-startjustify-endjustify-centerjustify-betweenjustify-around

Apple

Banana

Grape

Selection: Banana

<script setup>
import { ref } from 'vue'
import { AisRadioGroup } from '@ais-public/ais-components'
import { AisSelect } from '@ais-public/ais-components'

const justifications = ref([
  'justify-start', 'justify-end', 'justify-center',
  'justify-between', 'justify-around'
])
const selectedJustification = ref('justify-start')

const options = ref([
  'Apple', 'Banana', 'Grape'
])
const selection = ref('Banana')
</script>


<template>
  <div class="grid gap-4">
    <AisSelect
        v-model="selectedJustification"
        :options="justifications"
        size="sm"
    />

    <AisRadioGroup
        display="flex"
        class="p-4"
        :class="selectedJustification"
        v-model="selection"
        :options="options"
    />

    <div class="p-4 bg-ui-gray-50 border rounded">
      Selection: {{ selection }}
    </div>
  </div>
</template>

itemClass

Use the itemClass prop to customize styles on each radio button (i.e. the outermost wrapper on AisRadio). This is a good first option to try before falling back to the default slot and custom iteration for more precise control. In the example below, we add padding and a hover effect to each checkbox.

Beware that there are a number of global styles at play with radio groups. As a result, you may need to force the precedence on your styles using important utilities (e.g. !p-4). This will be particularly true for attributes like padding and text sizes. However, in the end some results may not be possible with the pre-built component and styles. If itemClass or the techniques mentioned above are not sufficient, developers may fall back to BaseCheckbox for complete control.

Apple

Banana

Grape

Kiwi

Selection: Banana

<script setup>
import { ref } from 'vue'
import { AisRadioGroup } from '@ais-public/ais-components'

const options = ref(['Apple', 'Banana', 'Grape', 'Kiwi'])
const selection = ref('Banana')
</script>

<template>
  <div class="grid gap-4">
    <AisRadioGroup
        display="grid"
        gap="gap-1"
        class="px-3 py-4 border border-ui-gray-100/75 rounded striped-reversed shadow"
        :options="options"
        v-model="selection"
        size="lg"
        itemClass="!p-2 hover:bg-ui-gray-100/40 hover:rounded"
    />
    <div class="p-4 bg-ui-gray-50 border rounded">
      Selection: {{ selection }}
    </div>
  </div>
</template>

Radio props

Radio props are attributes specified on the group and applied to the group's radio buttons whether they are defined through options or a slot. Note that these props will override corresponding values set on the individual radio buttons.

v-model

v-model will bind an array to all radio buttons in the group. When a radio is checked, its value (as specified by the value prop) will be included in the array. See [AisRadio](AisRadio#multiple-radio buttons) for further discussion. v-model is used in every example with a selection section.

name

The radio group will use the name prop to set the name attribute on all radio buttons in the group. If a name is not specified, then the group will generate a unique name. This is important when the group is part of a traditional form submission.

Specifying a name is also important when the group is marked as required. If any of the inputs in a same name group are marked required, then at least one of the radio buttons must be selected. How this requirement is enforced varies from browser to browser. Firefox will suppress the form's submit event until the browser validation is satisfied.

Option 1

Option 2

Body 1

Body 2

Selection: Option 2

<script setup>
import { ref } from 'vue'
import { AisRadioGroup, AisRadio } from '@ais-public/ais-components'

const options = ref(['Option 1', 'Option 2'])
const selection = ref('Option 2')
</script>

<template>
  <div class="grid gap-4">
    <AisRadioGroup
        class="px-4"
        :options="options"
        v-model="selection"
        name="example"
    >
      <AisRadio value="Body 1">Body 1</AisRadio>
      <AisRadio value="Body 2">Body 2</AisRadio>
    </AisRadioGroup>
    <div class="p-4 bg-ui-gray-50 border rounded">
      Selection: {{ selection }}
    </div>
  </div>
</template>

size

Setting the size prop on a radio group, will set the size on all radio buttons within the group. The group's size will take precedence over size values specified on individual radio buttons.

xssmmdlgxl2xl3xl

Option 1

Option 2

Body 1

Body 2

Selection: Body 2

<script setup>
import { ref } from 'vue'
import { AisRadioGroup } from '@ais-public/ais-components'
import { AisRadio } from '@ais-public/ais-components'
import { AisSelect } from '@ais-public/ais-components'


const options = ref(['Option 1', 'Option 2'])
const selectedSize = ref('md')
const selection = ref('Body 2')
</script>

<template>
  <div class="grid gap-4">
    <AisSelect v-model="selectedSize"
               :options="['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl']"
               size="sm"
    />
    <AisRadioGroup
        :options="options"
        v-model="selection"
        :size="selectedSize"
        class="px-4"
    >
      <AisRadio value="Body 1">Body 1</AisRadio>
      <AisRadio value="Body 2">Body 2</AisRadio>
    </AisRadioGroup>
    <div class="p-4 bg-ui-gray-50 border rounded">
      Selection: {{ selection }}
    </div>
  </div>
</template>

disabled

The disabled prop is a boolean prop on the group. When true, all radio buttons in the group will be disabled. Note that if either the group or radio is disabled then the radio will always be disabled. The group's setting can not enable a radio that has been explicitly disabled.

Disable:

Option 1

Option 2

Body 1

Body 2

Selection: Option 1

<script setup>
import { ref } from 'vue'
import { AisRadioGroup } from '@ais-public/ais-components'
import { AisRadio } from '@ais-public/ais-components'
import { AisToggle } from '@ais-public/ais-components'

const groupDisabled = ref(true)
const options = ref(['Option 1', 'Option 2'])
const selection = ref('Option 1')
</script>

<template>
  <div class="grid gap-4">
    <div class="flex items-center gap-3">
      Disable: <AisToggle v-model="groupDisabled" label="Disable" sr-label/>
    </div>

    <AisRadioGroup
        class="px-4"
        :options="options"
        v-model="selection"
        :disabled="groupDisabled"
    >
      <AisRadio value="Body 1">Body 1</AisRadio>
      <AisRadio value="Body 2" disabled>Body 2</AisRadio>
    </AisRadioGroup>
    <div class="p-4 bg-ui-gray-50 border rounded">
      Selection: {{ selection }}
    </div>
  </div>
</template>

invalid

The invalid prop will mark the group as invalid, when true. Invalid groups display in an error state with a red border and the error icon.

Option 1

Option 2

Option 3

<script setup>
import { ref } from 'vue'
import { AisRadioGroup } from '@ais-public/ais-components'

const options = ref(['Option 1', 'Option 2', 'Option 3'])
const selection = ref('Option 1')
</script>

<template>
  <div class="grid grid-cols-2 gap-4">
    <AisRadioGroup
        invalid
        :options="options"
        v-model="selection"
        class="p-1.5"
        size="md"
    />
  </div>
</template>

Button Group

An AisRadioGroup can be rendered as an AisButtonGroup by adding the buttons prop. Use the display prop to change the orientation (flex or grid). We recommend using the default variant for most use cases.

Section 1

Section 2

Section 3

Variant

defaultprimarysecondaryplaininfosuccesswarningdanger

Outline

Size

xssmmdlgxl

Display

flex (horizontal)grid (vertical)

Rounded

truefalsenonesmmdlgxl2xl3xlfull

<script setup>
  import { ref } from 'vue'
  import { variants } from "@/util/variants-util";
  import { controlSizes } from "@/util/controls";
  import { roundedStates } from "@/util/rounded-prop";

  import { AisRadioGroup } from '@ais-public/ais-components';
  import { AisField } from '@ais-public/ais-components';
  import { AisSelect } from '@ais-public/ais-components';
  import { AisToggle } from '@ais-public/ais-components';

  const selectedSection = ref('Section 2')
  const variant = ref('default')
  const size = ref('md')
  const rounded = ref(true)
  const display = ref('flex')
  const outline = ref(false)

  const sections = ref(['Section 1', 'Section 2', 'Section 3'])
  const displayOptions = ref([{ label: 'flex (horizontal)', value: 'flex'}, { label: 'grid (vertical)', value: 'grid'}])
</script>

<template>
  <div class="grid gap-8">
    <div class="flex gap-4 justify-center p-4 pb-8 border-b">
      <AisRadioGroup
        buttons
        v-model="selectedSection"
        :options="sections"
        :variant="variant"
        :outline="outline"
        :size="size"
        :rounded="rounded"
        :display="display"
      >
      </AisRadioGroup>
    </div>

    <div class="grid md:grid-cols-2 gap-x-8 gap-y-4  md:gap-y-8">
      <AisField label="Variant">
        <div class="grid gap-3">
          <AisSelect v-model="variant" :options="variants" class="grow"/>
          <AisToggle label="Outline" v-model="outline" rounded class="pl-0.5" />
        </div>
      </AisField>

      <AisField label="Size">
        <AisSelect v-model="size" :options="controlSizes" />
      </AisField>

      <AisField label="Display">
        <AisSelect v-model="display" :options="displayOptions" />
      </AisField>

      <AisField label="Rounded">
        <AisSelect v-model="rounded" :options="roundedStates" />
      </AisField>
    </div>
  </div>
</template>

buttons

Add the buttons prop to render the radio group as a button group. The following props only take effect when buttons is true.

variant

Use the variant prop to specify one of the button variants for the group.

outline

The outline prop can be combined with variant to provide an alternate set of button styles. outline is a boolean prop that can be added without a value. outline variants use a lighter background with a visible border.

rounded

The rounded prop controls the border radius of the group. The accepted values are: true, false, md, lg, and full. The default value is rounded.

Component Reference

Props

Property	Type(s)	Required	Default	Description	Deprecated
buttons	Boolean		false	When set, renders the radios in this group with button styling	false
disabled	Boolean		false	Places component in a disabled state, when true	false
disabledKey	String		'disabled'	The property in the option object used as the disabled flag	false
display	String		'flex'	The display prop sets the group's layout method. Valid values: flex, grid, inline-flex, inline-grid	false
gap	Array, String		() => ['gap-x-8', 'gap-y-4']	Use the gap prop to control spacing between radio buttons in the group container. The prop expects one or more Tailwind CSS gap classes; see: https://tailwindcss.com/docs/gap. By accepting multiple values, horizontal and vertical spacing can be controlled independently when using a grid.	false
iconKey	String		'icon'	The property in the option object that specifies an icon	false
invalid	Boolean		false	When set, indicates that the field is in an invalid state	false
itemClass	Array, String		''	The itemClass prop allows developers to customize the class definitions on each individual radio button in the group. This allows some customization without dropping down to using AisRadio in the group's body. There are global styles on radio groups, so setting attributes like padding may require flagging them as important (e.g. !p-4)	false
labelKey	String		'label'	The property in the option object that the user will see as the radio button label	false
modelValue	String		undefined	v-model prop. Used in conjunction with the event @update:modelValue	false
name	String		undefined	Sets the 'name' attribute on radio buttons created by or displayed within the group	false
options	Array		[]	Array of strings or objects used to populate the group's radio buttons. If an array of strings is provided, the string will be used for both the option's value and display string. If an object is provided, developers may specify the properties used to supply the value and display string. The defaults are 'id' and 'name'.	false
outline	Boolean		false	When set, the button will be displayed with the outline style	false
rounded	Boolean, String		undefined	When buttons=true, set the button group's border radius. Applies rounded corners using TailwindCSS's rounded classes	false
size	String		undefined	Set the size of the component's appearance Valid values: xs, sm, md, lg, xl, 2xl, 3xl	false
valueKey	String		'value'	The property in the option object to be used as the radio button value	false
variant	String		'default'	Specifies the variant to apply to the button style radios	false
buttonAlternate	Boolean		false	When set, the button will be displayed with the alternate variant style Deprecated - use outline instead	true
buttonFont	String		'caps'	Sets the font of the radio buttons Valid values: caps, sans, serif Deprecated No longer does anything	true
buttonVariant	String		'default'	Specifies the variant to apply to the button style radios Deprecated use variant instead	true

Slots

Name	Scoped	Description
default	No
head	No

Events

Event	Arguments	Description
update:modelValue