AisCheckboxGroup

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

Checkbox specification

A group's checkboxes 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 checkbox group is to bind the options prop to an array of strings.

Apple

Banana

Grape

Selection: []

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

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

<template>
  <div class="grid gap-4">
    <AisCheckboxGroup class="px-4"
        :options="options"
        v-model="selections"
    />
    <div class="p-4 bg-ui-gray-50 border rounded">
      Selection: {{ selections }}
    </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 checkbox: label, value, icon, iconOnly, tooltip, 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: []

<script setup>
import { ref } from 'vue';
import { AisCheckboxGroup } 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, tooltip: true },
  { label: 'George', value: 'george-harrison', icon: 'person', disabled: false, tooltip: 'primary' },
  { label: 'Ringo', value: 'ringo-starr', icon: 'person', disabled: false, tooltip: { content: 'ringo-star', variant: 'primary'} },
  { label: 'Pete', value: 'pete-best', icon: 'person', disabled: true },
]);
const selections = ref([]);
</script>

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

Default slot

In lieu of passing options, developers may also explicitly define checkboxes 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 checkboxes defined in the slot.

Bringing It All Back Home

Highway 61 Revisited

Blonde on Blonde

Basement Tapes

Selection: []

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

const selections = ref([]);
</script>

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

Head slot

Checkboxes generated by the options prop will appear before checkboxes 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: []

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

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

<template>
  <div class="grid gap-4">
    <AisCheckboxGroup
      :options="options"
      v-model="selections"
      class="px-4"
    >
      <template #head>
        <AisCheckbox value="Head 1">Head 1</AisCheckbox>
        <AisCheckbox value="Head 2">Head 2</AisCheckbox>
      </template>
    </AisCheckboxGroup>
    <div class="p-4 bg-ui-gray-50 border rounded">
      Selection: {{ selections }}
    </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 checkbox, 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: []

<script setup>
import { ref } from 'vue';
import { AisCheckboxGroup } from '@ais-public/ais-components';
import { AisCheckbox } 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 selections = ref([]);
</script>

<template>
  <div class="grid gap-4">
    <AisCheckboxGroup
        class="px-4"
        valueKey="label"
    >
      <AisCheckbox
          v-for="option in options"
          :id="`ch-${option.label}`"
          v-model="selections"
          :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>
      </AisCheckbox>
    </AisCheckboxGroup>
    <div class="p-4 bg-ui-gray-50 border rounded">
      Selection: {{ selections }}
    </div>
  </div>
</template>

Checkbox layout

The layout of a checkbox 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 checkboxes will expand horizontally with pleasant spacing. This layout works well for the typical case where we have a single row of checkboxes 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 checkboxes by setting display to grid.

Apple

Banana

Grape

Selection: []

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

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

<template>
  <div class="grid gap-4">
    <AisCheckboxGroup
      display="grid"
      gap="gap-1"
      class="px-4"
      :options="options"
      v-model="selections"
    />
    <div class="p-4 bg-ui-gray-50 border rounded">
      Selection: {{ selections }}
    </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: []

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

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

<template>
  <div class="grid gap-4">
    <AisCheckboxGroup
        gap="gap-x-24"
        class="px-4"
        :options="options"
        v-model="selections"
    />
    <div class="p-4 bg-ui-gray-50 border rounded">
      Selection: {{ selections }}
    </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: []

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

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


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

    <div class="p-4 bg-ui-gray-50 border rounded">
      Selection: {{ selections }}
    </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: []

<script setup>
import { ref } from 'vue';
import { AisCheckboxGroup } 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 selections = ref([]);
</script>


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

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

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

ItemClass

Use the itemClass prop to customize styles on each checkbox (i.e. the outermost wrapper on AisCheckbox). 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 checkbox 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: []

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

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

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

Checkbox props

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

v-model

v-model will bind an array to all checkboxes in the group. When a checkbox is checked, its value (as specified by the value prop) will be included in the array. See AisCheckbox for further discussion. v-model is used in every example with a selection section.

name

The checkbox group will use the name prop to set the name attribute on all inputs 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.

Option 1

Option 2

Body 1

Body 2

Selection: []

<script setup>
import { ref } from 'vue';
import { AisCheckboxGroup, AisCheckbox } from '@ais-public/ais-components';

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

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

size

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

xssmmdlgxl2xl

Option 1

Option 2

Body 1

Body 2

Selection: []

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

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

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

disabled

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

Disable:

Option 1

Option 2

Body 1

Body 2

Selection: []

<script setup>
import { ref } from 'vue';
import { AisCheckboxGroup } from '@ais-public/ais-components';
import { AisCheckbox } from '@ais-public/ais-components';
import { AisToggle } from '@ais-public/ais-components';

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

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

    <AisCheckboxGroup
        class="px-4"
        :options="options"
        v-model="selections"
        :disabled="groupDisabled"
    >
      <AisCheckbox value="Body 1">Body 1</AisCheckbox>
      <AisCheckbox value="Body 2" disabled>Body 2</AisCheckbox>
    </AisCheckboxGroup>
    <div class="p-4 bg-ui-gray-50 border rounded">
      Selection: {{ selections }}
    </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 { AisCheckboxGroup } from '@ais-public/ais-components';

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

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

iconOnly

iconOnly is a boolean prop that defaults to false. When true, the group's checkboxes will appear only with an icon. Each label will only be visible to screen readers, and as a tooltip. When using iconOnly, your options must include icon and label attributes. Any tooltip specification will be taken into account as well.

User

Group

World

Selection: []

<script setup>
import { ref } from 'vue';
import { AisCheckboxGroup } from '@ais-public/ais-components';
import { faGlobe } from "@fortawesome/free-solid-svg-icons";

const options = ref([
  { label: 'User', value: 'user', icon: 'user', disabled: false },
  { label: 'Group', value: 'group', icon: 'group', disabled: false },
  { label: 'World', value: 'world', icon: faGlobe, disabled: false },
]);
const selections = ref([]);
</script>

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

tooltip

tooltip controls tooltip configuration for the group. It accepts a boolean, variant, string, or object. The component combines tooltip with the label and tooltip attributes from an options object to create a fully specified tooltip definition (see AisTooltip's props for details).

John

Paul

George

Ringo

Pete

Selection: []

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

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

<template>
  <div class="grid gap-4">
    <AisCheckboxGroup
      :options="options"
      v-model="selections"
      :tooltip="{variant: 'primary', placement: 'bottom'}"
    />
    <div class="p-4 bg-ui-gray-50 border rounded">
      Selection: {{ selections }}
    </div>
  </div>
</template>

Events

@update:modelValue

@update:modelValue fires when the checkbox changes and drives the v-model directive. See the VueJS documentation for details.

@change

The @change event fires when the checkbox is checked or unchecked. The event's payload contains the checkbox's checked status and the checkbox's value. If the value is a number, the raw value can be found in the intValue attribute. @change is useful when you need to act on the last change and not on the entire selected set. For example, developers can use @change to toggle a database record when a checkbox is checked.

Payload: {}

Selection: []

one

two

three

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

let selection = ref([]);
let payload = ref({});
</script>

<template>
  <div class="mx-4 grid gap-2">
    <AisBox border-muted class="grid gap-4">
      <div>Payload: {{ payload }}</div>
      <div>Selection: {{ selection }}</div>
    </AisBox>

    <div class="px-1.5">
      <AisCheckboxGroup
          v-model="selection"
          :options="['one', 'two', 'three']"
          @change="payload=$event"
      />
    </div>
  </div>
</template>