AisCheckbox

AisCheckbox is a branded checkbox component that ensures a label is attached to the checkbox.

v-model

Single checkbox

At its most basic, use v-model to bind a single checkbox to a boolean value. The body of AisCheckbox will be used as the checkbox's label.

Checked: false

<script setup>
  import { ref } from 'vue';
  import { AisCheckbox } from '@ais-public/ais-components';
  let flag = ref(false);
</script>

<template>
  <div class="mx-4 flex gap-6">
    <AisCheckbox v-model="flag">
      Checked: {{flag}}
    </AisCheckbox>
  </div>
</template>

Multiple checkboxes

Values from related checkboxes may be collated using v-model to bind an array to each checkbox. Each element in the group should specify a value using the value prop. If the form will be submitted, the checkboxes should also share a name.

One

Two

Three

Four

Selection: [ "Two" ]

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

let options = ref(['One', 'Two', 'Three', 'Four']);
let selection = ref(['Two']);
</script>

<template>
  <div class="grid gap-4">
    <div class="mx-4 flex gap-8 items-center">
      <AisCheckbox
          v-for="option in options"
          v-model="selection" :value="option"
      >
        {{option}}
      </AisCheckbox>
    </div>
    <div class="bg-ui-gray-50 border rounded p-4">
      Selection: {{selection}}
    </div>
  </div>
</template>

Props

modelValue

modelValue powers the prop side of v-model. It works in conjunction with the @update:modelValue event. See the VueJS documentation for details.

value

The value prop sets the input element's value. When v-model is bound to an array, this is the value that will be added when checked. This is also the value that will be sumbitted if the form is submitted to a server.

checked

checked is a boolean prop that reflects the whether the checkbox is checked or not.

label

The label prop is set as the default value for the default slot. Developers may use either though any text provided in the body of the tag will override the label prop. When defining an iconOnly checkbox, you should prefer this prop as it will also be used to generate a tooltip. All checkboxes should specify either a label prop or a tag body to properly define an accessible label.

icon

AisCheckbox accepts an icon prop to display an icon alongside the checkbox. icon will accept either a FontAwesome icon definition or a string for one of our standard icons.

User

Group

World

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

import { faGlobe } from '@fortawesome/free-solid-svg-icons';
import { library } from '@fortawesome/fontawesome-svg-core';

let options = ref(['One', 'Two', 'Three', 'Four']);
let selection = ref([]);
library.add(faGlobe);
</script>

<template>
  <div class="mx-4 flex gap-8">
    <AisCheckbox icon="user" v-model="selection" value="user">User</AisCheckbox>
    <AisCheckbox icon="users" v-model="selection" value="group">Group</AisCheckbox>
    <AisCheckbox :icon="faGlobe" v-model="selection" value="world">World</AisCheckbox>
  </div>
</template>

iconOnly

iconOnly is a boolean prop that defaults to false. When true, the checkbox's label will only be shown to screen readers, and a tooltip will be shown on hover. When using iconOnly, prefer the label prop instead of the default slot. Any tooltip specification will take precedence. However, if tooltip is not specified, then the label prop will be used as the tooltip.

Expose to user ezra-koenig

Expose to group vampire-weekend

Expose to everyone

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

const user = ref(false);
const group = ref(false);
const world = ref(false);
</script>

<template>
  <div class="flex gap-2 p-4">
    <AisCheckbox
        v-model="user"
        :iconOnly="true"
        icon="user"
        label="Expose to user ezra-koenig"
    />
    <AisCheckbox
        v-model="group"
        :iconOnly="true"
        icon="group"
        label="Expose to group vampire-weekend"
        tooltip="secondary"
    />
    <AisCheckbox
      v-model="world"
      :iconOnly="true"
      :icon="faGlobe"
      label="Expose to everyone"
      tooltip="secondary"
    />
  </div>
</template>

tooltip

The tooltip prop will specify a tooltip for a checkbox. The prop may take either a boolean value, variant (e.g. "primary" or "success"), string (content text), or a tooltip options object. When passed true or a variant, the label prop will be used for the tooltip text.

User

Person

Group

World

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

  const booleanCheck = ref(false);
  const contentCheck = ref(false);
  const variantCheck = ref(false);
  const objectCheck = ref(false);
  const check = ref(false);

  const dynamicTooltip = computed(() => {
    return objectCheck.value ? "checked" : "unchecked";
  });
</script>

<template>
  <div class="flex gap-4 p-4">
    <AisCheckbox
        v-model="booleanCheck"
        icon="user"
        label="User"
        :tooltip="true"
    />

    <AisCheckbox
        v-model="contentCheck"
        icon="person"
        label="Person"
        tooltip="John"
    />

    <AisCheckbox
        v-model="variantCheck"
        icon="group"
        label="Group"
        tooltip="primary"
    />

    <AisCheckbox
        v-model="objectCheck"
        :icon="faGlobe"
        label="World"
        @change="(checked) => {check = checked.checked}"
        :tooltip="{variant: 'primary', placement: 'right', content: dynamicTooltip}"
    />
  </div>
</template>

size

Checkboxes accept a size property with the standard values of sm, md, and lg. Medium (md) is the default.

smmdlgxl2xl3xl

User

Group

World

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

import { faGlobe } from '@fortawesome/free-solid-svg-icons';
import { library } from '@fortawesome/fontawesome-svg-core';

let options = ref(['One', 'Two', 'Three', 'Four']);
let selection = ref([]);

const selectedSize = ref('md');

library.add(faGlobe);
</script>

<template>
  <div class="grid gap-8">
    <AisSelect v-model="selectedSize"
               :options="['sm', 'md', 'lg', 'xl', '2xl', '3xl']"
               size="sm"
    />
    <div class="mx-4 flex gap-8">
      <AisCheckbox :size="selectedSize" icon="user" v-model="selection" value="user">User</AisCheckbox>
      <AisCheckbox :size="selectedSize" icon="users" v-model="selection" value="group">Group</AisCheckbox>
      <AisCheckbox :size="selectedSize" :icon="faGlobe" v-model="selection" value="world">World</AisCheckbox>
    </div>
  </div>
</template>

name

The name prop will set the name attribute on the checkbox. It is required if the form will be submitted to a server. It is also recommended to provide a name when iterating over a list of options to create a checkbox group.

disabled

Checkboxes accept a boolean disabled property. Disabled checkboxes are not clickable and are not submitted with its form.

Checked: false

<script setup>
  import { ref } from 'vue';
  import { AisCheckbox } from '@ais-public/ais-components';
  let flag = ref(false);
</script>

<template>
  <div class="mx-4 flex gap-6">
    <AisCheckbox v-model="flag" :disabled="true">
      Checked: {{flag}}
    </AisCheckbox>
  </div>
</template>

invalid

Checkboxes accept a boolean invalid and flagError properties to highlight and customize invalid checkboxes. When invalid is true, the checkbox will be styled with a red border. If flagError is true (as it is by default), the error icon will also appear. AisCheckboxGroup disables flagError as it handles error styling at the group level.

Invalid Example

flagError

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

  let flag = ref(false);
  let flagError = ref(true);
</script>

<template>
  <div class="mx-4 flex gap-4">
    <AisCheckbox icon="info" v-model="flag" :invalid="!flag" :flagError="flagError">
      Invalid Example
    </AisCheckbox>

    <AisToggle label="flagError"
               v-model="flagError"
               size="sm"
               variant="danger"
    />
  </div>
</template>

required

The required prop marks the checkbox as required and activates browser validation. If a checkbox is required, then it must be checked to satisfy the browser validation. This is true whether the checkbox stands alone or is part of a same name group. As a result, checkboxes will not inherit required status from AisField or other ancestors. Checkboxes must be explicitly marked as required through the prop.

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.

Payload: {}

Click to @change

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

let flag = ref(false);
let payload = ref({});
</script>

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

    <div class="px-1.5">
      <AisCheckbox
          v-model="flag"
          value="50"
          @change="payload=$event"
      >
        Click to @change
      </AisCheckbox>
    </div>
  </div>
</template>