The Checkbox component allows users to make a binary choice, such as toggling an option on or off. It’s commonly used in forms and settings.

Anatomy

Usage

Basic Example

A standard checkbox with a label.

Label

Show code

React

import { PlusCheckbox } from '@plusui/react';

export default () => {
  return (
    <>
      <PlusCheckbox>
        Label
      </PlusCheckbox>
    </>
  );
};

Angular

import { Component } from '@angular/core';

@Component({
  selector: 'app-example',
  template: `
    <plus-checkbox>
      Label
    </plus-checkbox>
  `
})
export class ExampleComponent {}

Vue

<template>
  <plus-checkbox>
    Label
  </plus-checkbox>
</template>

Svelte

<plus-checkbox>
  Label
</plus-checkbox>

HTML

<plus-checkbox>
  Label
</plus-checkbox>

Checked State

Use the checked prop to control the selection state. The indeterminate prop represents a state where the checkbox is neither checked nor unchecked, often used in parent checkboxes.

UncheckedCheckedIndeterminate

Show code

React

import { PlusCheckbox } from '@plusui/react';

export default () => {
  return (
    <>
      <PlusCheckbox>
        Unchecked
      </PlusCheckbox>
      <PlusCheckbox checked>
        Checked
      </PlusCheckbox>
      <PlusCheckbox indeterminate="true">
        Indeterminate
      </PlusCheckbox>
    </>
  );
};

Angular

import { Component } from '@angular/core';

@Component({
  selector: 'app-example',
  template: `
    <plus-checkbox>
      Unchecked
    </plus-checkbox>
    <plus-checkbox checked>
      Checked
    </plus-checkbox>
    <plus-checkbox indeterminate="true">
      Indeterminate
    </plus-checkbox>
  `
})
export class ExampleComponent {}

Vue

<template>
  <plus-checkbox>
    Unchecked
  </plus-checkbox>
  <plus-checkbox checked>
    Checked
  </plus-checkbox>
  <plus-checkbox indeterminate="true">
    Indeterminate
  </plus-checkbox>
</template>

Svelte

<plus-checkbox>
  Unchecked
</plus-checkbox>
<plus-checkbox checked>
  Checked
</plus-checkbox>
<plus-checkbox indeterminate="true">
  Indeterminate
</plus-checkbox>

HTML

<plus-checkbox>
  Unchecked
</plus-checkbox>
<plus-checkbox checked>
  Checked
</plus-checkbox>
<plus-checkbox indeterminate="true">
  Indeterminate
</plus-checkbox>

Size

The size prop controls the checkbox dimensions.

SizeSizeSize

Show code

React

import { PlusCheckbox } from '@plusui/react';

export default () => {
  return (
    <>
      <PlusCheckbox size="sm">
        Size
      </PlusCheckbox>
      <PlusCheckbox size="md">
        Size
      </PlusCheckbox>
      <PlusCheckbox size="lg">
        Size
      </PlusCheckbox>
    </>
  );
};

Angular

import { Component } from '@angular/core';

@Component({
  selector: 'app-example',
  template: `
    <plus-checkbox size="sm">
      Size
    </plus-checkbox>
    <plus-checkbox size="md">
      Size
    </plus-checkbox>
    <plus-checkbox size="lg">
      Size
    </plus-checkbox>
  `
})
export class ExampleComponent {}

Vue

<template>
  <plus-checkbox size="sm">
    Size
  </plus-checkbox>
  <plus-checkbox size="md">
    Size
  </plus-checkbox>
  <plus-checkbox size="lg">
    Size
  </plus-checkbox>
</template>

Svelte

<plus-checkbox size="sm">
  Size
</plus-checkbox>
<plus-checkbox size="md">
  Size
</plus-checkbox>
<plus-checkbox size="lg">
  Size
</plus-checkbox>

HTML

<plus-checkbox size="sm">
  Size
</plus-checkbox>
<plus-checkbox size="md">
  Size
</plus-checkbox>
<plus-checkbox size="lg">
  Size
</plus-checkbox>

Disabled State

Set the disabled attribute or prop to prevent user interaction.

Disabled UncheckedDisabled CheckedDisabled Indeterminate

Show code

React

import { PlusCheckbox } from '@plusui/react';

export default () => {
  return (
    <>
      <PlusCheckbox disabled>
        Disabled Unchecked
      </PlusCheckbox>
      <PlusCheckbox checked disabled>
        Disabled Checked
      </PlusCheckbox>
      <PlusCheckbox indeterminate="true" disabled>
        Disabled Indeterminate
      </PlusCheckbox>
    </>
  );
};

Angular

import { Component } from '@angular/core';

@Component({
  selector: 'app-example',
  template: `
    <plus-checkbox disabled>
      Disabled Unchecked
    </plus-checkbox>
    <plus-checkbox checked disabled>
      Disabled Checked
    </plus-checkbox>
    <plus-checkbox indeterminate="true" disabled>
      Disabled Indeterminate
    </plus-checkbox>
  `
})
export class ExampleComponent {}

Vue

<template>
  <plus-checkbox disabled>
    Disabled Unchecked
  </plus-checkbox>
  <plus-checkbox checked disabled>
    Disabled Checked
  </plus-checkbox>
  <plus-checkbox indeterminate="true" disabled>
    Disabled Indeterminate
  </plus-checkbox>
</template>

Svelte

<plus-checkbox disabled>
  Disabled Unchecked
</plus-checkbox>
<plus-checkbox checked disabled>
  Disabled Checked
</plus-checkbox>
<plus-checkbox indeterminate="true" disabled>
  Disabled Indeterminate
</plus-checkbox>

HTML

<plus-checkbox disabled>
  Disabled Unchecked
</plus-checkbox>
<plus-checkbox checked disabled>
  Disabled Checked
</plus-checkbox>
<plus-checkbox indeterminate="true" disabled>
  Disabled Indeterminate
</plus-checkbox>

Error State

Set the error attribute or prop to indicate a validation error.

Error UncheckedError CheckedError Indeterminate

Show code

React

import { PlusCheckbox } from '@plusui/react';

export default () => {
  return (
    <>
      <PlusCheckbox error="true">
        Error Unchecked
      </PlusCheckbox>
      <PlusCheckbox checked error="true">
        Error Checked
      </PlusCheckbox>
      <PlusCheckbox indeterminate="true" error="true">
        Error Indeterminate
      </PlusCheckbox>
    </>
  );
};

Angular

import { Component } from '@angular/core';

@Component({
  selector: 'app-example',
  template: `
    <plus-checkbox error="true">
      Error Unchecked
    </plus-checkbox>
    <plus-checkbox checked error="true">
      Error Checked
    </plus-checkbox>
    <plus-checkbox indeterminate="true" error="true">
      Error Indeterminate
    </plus-checkbox>
  `
})
export class ExampleComponent {}

Vue

<template>
  <plus-checkbox error="true">
    Error Unchecked
  </plus-checkbox>
  <plus-checkbox checked error="true">
    Error Checked
  </plus-checkbox>
  <plus-checkbox indeterminate="true" error="true">
    Error Indeterminate
  </plus-checkbox>
</template>

Svelte

<plus-checkbox error="true">
  Error Unchecked
</plus-checkbox>
<plus-checkbox checked error="true">
  Error Checked
</plus-checkbox>
<plus-checkbox indeterminate="true" error="true">
  Error Indeterminate
</plus-checkbox>

HTML

<plus-checkbox error="true">
  Error Unchecked
</plus-checkbox>
<plus-checkbox checked error="true">
  Error Checked
</plus-checkbox>
<plus-checkbox indeterminate="true" error="true">
  Error Indeterminate
</plus-checkbox>

Labeling

You can provide the label text either via the default slot or the text prop. The default slot takes precedence.

Label via Slot

Show code

React

import { PlusCheckbox } from '@plusui/react';

export default () => {
  return (
    <>
      <PlusCheckbox>
        Label via Slot
      </PlusCheckbox>
      <PlusCheckbox text="Label via Prop">
      </PlusCheckbox>
    </>
  );
};

Angular

import { Component } from '@angular/core';

@Component({
  selector: 'app-example',
  template: `
    <plus-checkbox>
      Label via Slot
    </plus-checkbox>
    <plus-checkbox text="Label via Prop">
    </plus-checkbox>
  `
})
export class ExampleComponent {}

Vue

<template>
  <plus-checkbox>
    Label via Slot
  </plus-checkbox>
  <plus-checkbox text="Label via Prop">
  </plus-checkbox>
</template>

Svelte

<plus-checkbox>
  Label via Slot
</plus-checkbox>
<plus-checkbox text="Label via Prop">
</plus-checkbox>

HTML

<plus-checkbox>
  Label via Slot
</plus-checkbox>
<plus-checkbox text="Label via Prop">
</plus-checkbox>

Handling Changes

Listen for the plus-change event to react when the checked state changes.

Notify on Change

Show code

React

import { PlusCheckbox } from '@plusui/react';
import { useState } from 'react';

export default () => {
  const [isChecked, setIsChecked] = useState(false);

  const handleChange = (event) => {
    console.log('Checkbox changed:', event.target.checked);
    setIsChecked(event.target.checked);
  };

  return (
    <PlusCheckbox checked={isChecked} onPlusChange={handleChange}>
      Notify on Change
    </PlusCheckbox>
  );
};

Angular

import { Component } from '@angular/core';

@Component({
  selector: 'app-checkbox-change',
  template: `
    <plus-checkbox (plus-change)="handleChange($event)">
      Notify on Change
    </plus-checkbox>
  `
})
export class CheckboxChangeComponent {
  handleChange(event: any) {
    console.log('Checkbox changed:', event.target.checked);
  }
}

Vue

<template>
  <plus-checkbox @plus-change="handleChange">
    Notify on Change
  </plus-checkbox>
</template>

<script setup>
const handleChange = (event) => {
  console.log('Checkbox changed:', event.target.checked);
};
</script>

Svelte

<script>
  import { onMount } from 'svelte';

  let checkboxElement;

  onMount(() => {
    if (checkboxElement) {
      checkboxElement.addEventListener('plus-change', (event) => {
        console.log('Checkbox changed:', event.target.checked);
      });
    }
  });
</script>

<plus-checkbox bind:this={checkboxElement}>
  Notify on Change
</plus-checkbox>

HTML

<plus-checkbox id="change-checkbox-html">Notify on Change</plus-checkbox>

<script>
  document.getElementById('change-checkbox-html').addEventListener('plus-change', (event) => {
    console.log('Checkbox changed:', event.target.checked);
  });
</script>

Show console

Console Output:

No console output yet. Try interacting with the components above.

Clear Console

Checkbox Group

Use the plus-checkbox-group component to group related checkboxes. The group manages the value (an array of checked checkbox values) and can control properties like size and disabled for all nested checkboxes. Use the vertical prop on the group to arrange checkboxes vertically.

HTMLCSSReactAngularVueSvelte (disabled)

Show code

React

import { PlusCheckbox, PlusCheckboxGroup } from '@plusui/react';
import { useState } from 'react';

export default () => {
  const [groupValue, setGroupValue] = useState(['react', 'vue']);

  const handleGroupChange = (event) => {
    console.log('Group value changed:', event.detail.value);
    setGroupValue(event.detail.value);
  };

  return (
    <PlusCheckboxGroup
      value={groupValue}
      vertical
      size="sm"
      onPlusChange={handleGroupChange}
    >
      <PlusCheckbox value="html">HTML</PlusCheckbox>
      <PlusCheckbox value="css">CSS</PlusCheckbox>
      <PlusCheckbox value="react">React</PlusCheckbox>
      <PlusCheckbox value="angular">Angular</PlusCheckbox>
      <PlusCheckbox value="vue">Vue</PlusCheckbox>
      <PlusCheckbox value="svelte" disabled>Svelte (disabled)</PlusCheckbox>
    </PlusCheckboxGroup>
  );
};

Angular

import { Component } from '@angular/core';

@Component({
  selector: 'app-checkbox-group',
  template: `
    <plus-checkbox-group
      [value]="groupValue"
      vertical
      size="sm"
      (plus-change)="handleGroupChange($event)"
    >
      <plus-checkbox value="html">HTML</plus-checkbox>
      <plus-checkbox value="css">CSS</plus-checkbox>
      <plus-checkbox value="react">React</plus-checkbox>
      <plus-checkbox value="angular">Angular</plus-checkbox>
      <plus-checkbox value="vue">Vue</plus-checkbox>
      <plus-checkbox value="svelte" disabled>Svelte (disabled)</plus-checkbox>
    </plus-checkbox-group>
  `
})
export class CheckboxGroupComponent {
  groupValue = ['react', 'vue'];

  handleGroupChange(event: any) {
    console.log('Group value changed:', event.detail.value);
    this.groupValue = event.detail.value;
  }
}

Vue

<template>
  <plus-checkbox-group
    :value="groupValue"
    vertical
    size="sm"
    @plus-change="handleGroupChange"
  >
    <plus-checkbox value="html">HTML</plus-checkbox>
    <plus-checkbox value="css">CSS</plus-checkbox>
    <plus-checkbox value="react">React</plus-checkbox>
    <plus-checkbox value="angular">Angular</plus-checkbox>
    <plus-checkbox value="vue">Vue</plus-checkbox>
    <plus-checkbox value="svelte" disabled>Svelte (disabled)</plus-checkbox>
  </plus-checkbox-group>
</template>

<script setup>
import { ref } from 'vue';

const groupValue = ref(['react', 'vue']);

const handleGroupChange = (event) => {
  console.log('Group value changed:', event.detail.value);
  groupValue.value = event.detail.value;
};
</script>

Svelte

<script>
  import { onMount } from 'svelte';

  let groupValue = ['react', 'vue'];
  let groupElement;

  onMount(() => {
    if (groupElement) {
      groupElement.addEventListener('plus-change', (event) => {
        console.log('Group value changed:', event.detail.value);
        groupValue = event.detail.value;
      });
    }
  });
</script>

<plus-checkbox-group
  bind:this={groupElement}
  value={JSON.stringify(groupValue)}
  vertical
  size="sm"
>
  <plus-checkbox value="html">HTML</plus-checkbox>
  <plus-checkbox value="css">CSS</plus-checkbox>
  <plus-checkbox value="react">React</plus-checkbox>
  <plus-checkbox value="angular">Angular</plus-checkbox>
  <plus-checkbox value="vue">Vue</plus-checkbox>
  <plus-checkbox value="svelte" disabled>Svelte (disabled)</plus-checkbox>
</plus-checkbox-group>

HTML

<plus-checkbox-group value='["react", "vue"]' vertical size="sm" id="checkbox-group">
  <plus-checkbox value="html">HTML</plus-checkbox>
  <plus-checkbox value="css">CSS</plus-checkbox>
  <plus-checkbox value="react">React</plus-checkbox>
  <plus-checkbox value="angular">Angular</plus-checkbox>
  <plus-checkbox value="vue">Vue</plus-checkbox>
  <plus-checkbox value="svelte" disabled>Svelte (disabled)</plus-checkbox>
</plus-checkbox-group>

<script>
  document.getElementById('checkbox-group').addEventListener('plus-change', (event) => {
    console.log('Group value changed:', event.detail.value);
  });
</script>

Show console

Console Output:

No console output yet. Try interacting with the components above.

Clear Console

Visual Sections

Layout & Spacing

Light & Dark Mode

Accessibility (a11y)

• Keyboard Behavior:
  • Checkboxes are focusable via the Tab key.
  • The state can be toggled using the Space key when focused.
• Screen Reader:
  • Uses a native <input type="checkbox"> internally, ensuring standard screen reader announcements for state (checked, unchecked, mixed, disabled).
  • The label provided via the slot or text prop serves as the accessible name, linked via the <label> element.
  • aria-checked is set to true, false, or mixed based on the checked and indeterminate props.
  • aria-disabled is set based on the disabled prop.
  • aria-invalid is set based on the error prop.
• Required Developer Actions:
  • Always provide a visible label either through the default slot or the text prop. Avoid using checkboxes without labels.
  • Ensure sufficient color contrast between the checkbox and its background, and the checkmark/text and the checkbox background, especially when customizing colors.

Design System

Plus UI Design System on Figma

Visit

API Reference

Note

This section covers the API for both plus-checkbox and plus-checkbox-group.

Properties (plus-checkbox)

Name	Type	Default	Description	Required
name	string	undefined	The name attribute for the internal input, used in form submission.	No
size	'sm' | 'md' | 'lg'	'md'	Size of the checkbox. Inherited from group if nested.	No
checked	boolean	false	Whether the checkbox is checked. Managed by group if nested.	No
indeterminate	boolean	false	Whether the checkbox is in an indeterminate state.	No
disabled	boolean	false	Whether the checkbox is disabled. Inherited from group if nested.	No
value	string	'on'	The value submitted with form data when the checkbox is checked.	No
error	boolean	false	Displays the checkbox in an error state (e.g., invalid input).	No
text	string	undefined	Text label for the checkbox (alternative to default slot). The slot takes precedence.	No

Properties (plus-checkbox-group)

Name	Type	Default	Description	Required
value	string[]	[]	An array of values corresponding to the checked checkboxes.	No
vertical	boolean	false	If true, displays checkboxes vertically instead of horizontally.	No
size	'sm' | 'md' | 'lg'	'md'	Sets the size for all nested checkboxes.	No
disabled	boolean	false	Disables all nested checkboxes.	No

Events (plus-checkbox)

Name	Payload Type	Description
plus-change	Event	Fired when the checked state changes.
plus-focus	FocusEvent	Fired when the checkbox gains focus.
plus-blur	FocusEvent	Fired when the checkbox loses focus.

Events (plus-checkbox-group)

Name	Payload Type	Description
plus-change	CustomEvent<{ value: string[] }>	Fired when the group’s value changes (any checkbox toggled).

Slots (plus-checkbox)

Name	Description
default (unnamed)	The label content for the checkbox. Overrides text.

Slots (plus-checkbox-group)

Name	Description
default (unnamed)	Container for plus-checkbox elements.

CSS Shadow Parts (plus-checkbox)

Part	Description
base	The main container element (<label>).
control	The container wrapping the visual checkbox and the native input.
checkbox	The visual representation of the checkbox box.
icon	The checkmark or indeterminate icon (<plus-icon>).
label	The container for the label text (slot content or text prop).

CSS Shadow Parts (plus-checkbox-group)

Part	Description
base	The main container element (div).

CSS Custom Properties (plus-checkbox)

Name	Description
--checkbox-size	Controls the size of the checkbox control.
--checkbox-color-default	Default background color of the checkbox.
--checkbox-color-checked	Background color when checked or indeterminate.
--checkbox-color-border	Border color of the checkbox.
--checkbox-color-border-checked	Border color when checked or indeterminate.
--checkbox-color-icon	Color of the checkmark or indeterminate icon.
--checkbox-border-color-error	Border color when in the error state.

Note

plus-checkbox-group does not expose specific CSS custom properties; styling is primarily controlled via the nested plus-checkbox elements.

Join the Community

Plus UI is built by the community. Join us on our platforms to contribute, get help, and stay up to date.

Figma GitHub Discord Twitter Open Collective