Checkbox

<afp-checkbox>

stable

This component uses the light DOM, so its markup and styles are part of the regular document flow.

The Checkbox component allows users to select or deselect a single option. It supports multiple states including checked, unchecked, disabled, and indeterminate.

<afp-checkbox hidelabel></afp-checkbox>

<afp-checkbox hidelabel></afp-checkbox>

<AfpCheckbox hidelabel></AfpCheckbox>

<AfpCheckbox hidelabel></AfpCheckbox>

Examples #

Shapes #

Use the shape attribute to set the shape of the checkbox. Available shapes are square and rounded.

Pill

Rounded

Soft

Square

<div class="afp-cluster afp-align-center">
  <afp-checkbox shape="pill" checked>Pill</afp-checkbox>
  <afp-checkbox shape="rounded" checked>Rounded</afp-checkbox>
  <afp-checkbox shape="soft" checked>Soft</afp-checkbox>
  <afp-checkbox shape="square" checked>Square</afp-checkbox>
</div>

<div class="afp-cluster afp-align-center">
  <afp-checkbox [shape]="'pill'" checked>Pill</afp-checkbox>
  <afp-checkbox [shape]="'rounded'" checked>Rounded</afp-checkbox>
  <afp-checkbox [shape]="'soft'" checked>Soft</afp-checkbox>
  <afp-checkbox [shape]="'square'" checked>Square</afp-checkbox>
</div>

<div class="afp-cluster afp-align-center">
  <AfpCheckbox shape="pill" checked>Pill</AfpCheckbox>
  <AfpCheckbox shape="rounded" checked>Rounded</AfpCheckbox>
  <AfpCheckbox shape="soft" checked>Soft</AfpCheckbox>
  <AfpCheckbox shape="square" checked>Square</AfpCheckbox>
</div>

<div class="afp-cluster afp-align-center">
  <AfpCheckbox :shape="'pill'" checked>Pill</AfpCheckbox>
  <AfpCheckbox :shape="'rounded'" checked>Rounded</AfpCheckbox>
  <AfpCheckbox :shape="'soft'" checked>Soft</AfpCheckbox>
  <AfpCheckbox :shape="'square'" checked>Square</AfpCheckbox>
</div>

Sizes #

Use the size attribute to set the size of the checkbox. Available sizes are small, medium, and large.

Small

Medium

Large

<div class="afp-cluster afp-align-center">
  <afp-checkbox size="small">Small</afp-checkbox>
  <afp-checkbox size="medium">Medium</afp-checkbox>
  <afp-checkbox size="large">Large</afp-checkbox>
</div>

<div class="afp-cluster afp-align-center">
  <afp-checkbox [size]="'small'">Small</afp-checkbox>
  <afp-checkbox [size]="'medium'">Medium</afp-checkbox>
  <afp-checkbox [size]="'large'">Large</afp-checkbox>
</div>

<div class="afp-cluster afp-align-center">
  <AfpCheckbox size="small">Small</AfpCheckbox>
  <AfpCheckbox size="medium">Medium</AfpCheckbox>
  <AfpCheckbox size="large">Large</AfpCheckbox>
</div>

<div class="afp-cluster afp-align-center">
  <AfpCheckbox :size="'small'">Small</AfpCheckbox>
  <AfpCheckbox :size="'medium'">Medium</AfpCheckbox>
  <AfpCheckbox :size="'large'">Large</AfpCheckbox>
</div>

Hint #

Use the hint attribute to provide additional information below the checkbox.

Accept terms

<afp-checkbox hint="Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua">Accept terms</afp-checkbox>

<afp-checkbox [hint]="'Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua'">Accept terms</afp-checkbox>

<AfpCheckbox hint="Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua">Accept terms</AfpCheckbox>

<AfpCheckbox :hint="'Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua'">Accept terms</AfpCheckbox>

Value #

Use the afp-value-changed event to listen for value changes.

Click me

<afp-checkbox id="demo-checkbox" hint="Event output:" value="demo">Click me</afp-checkbox>

<script>
  document.addEventListener("DOMContentLoaded", () => {
    const checkboxEl = document.querySelector('#demo-checkbox');

    checkboxEl.addEventListener('afp-value-changed', (event) => {
      checkboxEl.hint = `Event output: ${JSON.stringify(event.detail)}`;
    });
  });
</script>

<afp-checkbox [id]="'demo-checkbox'" [hint]="'Event output:'" [value]="'demo'">Click me</afp-checkbox>

<script>
  document.addEventListener("DOMContentLoaded", () => {
    const checkboxEl = document.querySelector('#demo-checkbox');

    checkboxEl.addEventListener('afp-value-changed', (event) => {
      checkboxEl.hint = `Event output: ${JSON.stringify(event.detail)}`;
    });
  });
</script>

<AfpCheckbox id="demo-checkbox" hint="Event output:" value="demo">Click me</AfpCheckbox>

<script>
  document.addEventListener("DOMContentLoaded", () => {
    const checkboxEl = document.querySelector('#demo-checkbox');

    checkboxEl.addEventListener('afp-value-changed', (event) => {
      checkboxEl.hint = `Event output: ${JSON.stringify(event.detail)}`;
    });
  });
</script>

<AfpCheckbox :id="'demo-checkbox'" :hint="'Event output:'" :value="'demo'">Click me</AfpCheckbox>

<script>
  document.addEventListener("DOMContentLoaded", () => {
    const checkboxEl = document.querySelector('#demo-checkbox');

    checkboxEl.addEventListener('afp-value-changed', (event) => {
      checkboxEl.hint = `Event output: ${JSON.stringify(event.detail)}`;
    });
  });
</script>

Checked #

Use the checked attribute to render a checkbox in the checked state.

Checked checkbox

<afp-checkbox checked>Checked checkbox</afp-checkbox>

<afp-checkbox checked>Checked checkbox</afp-checkbox>

<AfpCheckbox checked>Checked checkbox</AfpCheckbox>

<AfpCheckbox checked>Checked checkbox</AfpCheckbox>

Disabled #

Use the disabled attribute to render a checkbox in the disabled state.

Receive notifications (disabled)

Receive notifications (disabled, checked)

<div class="afp-stack">
  <afp-checkbox disabled>Receive notifications (disabled)</afp-checkbox>
  <afp-checkbox disabled checked>Receive notifications (disabled, checked)</afp-checkbox>
</div>

<div class="afp-stack">
  <afp-checkbox disabled>Receive notifications (disabled)</afp-checkbox>
  <afp-checkbox disabled checked>Receive notifications (disabled, checked)</afp-checkbox>
</div>

<div class="afp-stack">
  <AfpCheckbox disabled>Receive notifications (disabled)</AfpCheckbox>
  <AfpCheckbox disabled checked>Receive notifications (disabled, checked)</AfpCheckbox>
</div>

<div class="afp-stack">
  <AfpCheckbox disabled>Receive notifications (disabled)</AfpCheckbox>
  <AfpCheckbox disabled checked>Receive notifications (disabled, checked)</AfpCheckbox>
</div>

Invalid #

Use the invalid attribute to render a checkbox in the invalid state with an error message.

Accept terms

<afp-checkbox invalid="This field is required">Accept terms</afp-checkbox>

<afp-checkbox [invalid]="'This field is required'">Accept terms</afp-checkbox>

<AfpCheckbox invalid="This field is required">Accept terms</AfpCheckbox>

<AfpCheckbox :invalid="'This field is required'">Accept terms</AfpCheckbox>

Indeterminate #

Use the indeterminate attribute to render a checkbox in the indeterminate state.

Indeterminate checkbox

<afp-checkbox indeterminate>Indeterminate checkbox</afp-checkbox>

<afp-checkbox indeterminate>Indeterminate checkbox</afp-checkbox>

<AfpCheckbox indeterminate>Indeterminate checkbox</AfpCheckbox>

<AfpCheckbox indeterminate>Indeterminate checkbox</AfpCheckbox>

Custom Icons #

Use the checked-icon and indeterminate-icon slots to provide custom icons for the checked and indeterminate states.

Custom checked icon

Custom indeterminate icon

<div class="afp-stack">
  <afp-checkbox checked>
    <afp-icon slot="checked-icon" name="x" label="Error"></afp-icon>
    Custom checked icon
  </afp-checkbox>
  <afp-checkbox indeterminate>
    <afp-icon slot="indeterminate-icon" name="dash-lg" label="Error"></afp-icon>
    Custom indeterminate icon
  </afp-checkbox>
</div>

<div class="afp-stack">
  <afp-checkbox checked>
    <afp-icon [slot]="'checked-icon'" [name]="'x'" [label]="'Error'"></afp-icon>
    Custom checked icon
  </afp-checkbox>
  <afp-checkbox indeterminate>
    <afp-icon [slot]="'indeterminate-icon'" [name]="'dash-lg'" [label]="'Error'"></afp-icon>
    Custom indeterminate icon
  </afp-checkbox>
</div>

<div class="afp-stack">
  <AfpCheckbox checked>
    <AfpIcon slot="checked-icon" name="x" label="Error"></AfpIcon>
    Custom checked icon
  </AfpCheckbox>
  <AfpCheckbox indeterminate>
    <AfpIcon slot="indeterminate-icon" name="dash-lg" label="Error"></AfpIcon>
    Custom indeterminate icon
  </AfpCheckbox>
</div>

<div class="afp-stack">
  <AfpCheckbox checked>
    <AfpIcon :slot="'checked-icon'" :name="'x'" :label="'Error'"></AfpIcon>
    Custom checked icon
  </AfpCheckbox>
  <AfpCheckbox indeterminate>
    <AfpIcon :slot="'indeterminate-icon'" :name="'dash-lg'" :label="'Error'"></AfpIcon>
    Custom indeterminate icon
  </AfpCheckbox>
</div>

Customization #

Use the --afp-checkbox-color and --afp-checkbox-background CSS variables to customize the checkbox appearance.

Custom colors

<afp-checkbox checked style="--afp-checkbox-background: deeppink; --afp-checkbox-color: white">Custom colors</afp-checkbox>

<afp-checkbox checked [style]="'--afp-checkbox-background: deeppink; --afp-checkbox-color: white'">Custom colors</afp-checkbox>

<AfpCheckbox checked style="--afp-checkbox-background: deeppink; --afp-checkbox-color: white">Custom colors</AfpCheckbox>

<AfpCheckbox checked :style="'--afp-checkbox-background: deeppink; --afp-checkbox-color: white'">Custom colors</AfpCheckbox>

Properties

Learn more about properties.

Name Description Reflects

checked

Checked state of the checkbox.

Type boolean

Default false

defaultchecked

Default checked attribute of the checkbox. The checkbox is initialized with checked = true when defaultchecked is true.

Type boolean

Default false

hideLabel
hidelabel

Hides the label visually

Type boolean

disabled

Disabled state of the checkbox.

Type boolean

Default false

indeterminate

Indeterminate state of the checkbox.

Type boolean

Default false

invalid

Error message shown below the checkbox when present. Sets `aria-invalid`. Provide a non-empty string to put the component in an error state.

Type string

hint

hint footer property of checkbox

Type string

shape

shape of the checkbox

Type

AfpShape

Name	Description
`PILL`	Makes the component circular.
`ROUNDED`	Makes the component rounded.
`SOFT`	Makes the component have soft edges.
`SQUARE`	Makes the component square.

AfpShape

Default AfpShape.ROUNDED

name

Name of the input element.

Type string

required

Required attribute of the checkbox.

Type boolean

Default false

size

Size of the checkbox

Type

AfpSize

Name	Description
`SMALL`	Small size with compact dimensions.
`MEDIUM`	Medium size with standard dimensions.
`LARGE`	Large size with expanded dimensions.

AfpSize

Default AfpSize.MEDIUM

value

Value of the input element.

Type number | string | undefined

Default undefined

Methods

Learn more about using methods.

Name	Description	Arguments
`doFocus`	Focus the checkbox input	-
`doBlur`	Blur the checkbox input	-
`doClick`	Click the checkbox input	-

Events

Learn more about events.

Name	Return	Description
`afp-value-changed`	`{ value: number \| string \| undefined; checked: boolean }`	Emitted when the checkbox value changes.
`afp-change`	`boolean`	Emitted when the checked state changes.
`afp-focus`	`void`	Emitted when the checkbox gains focus.
`afp-blur`	`void`	Emitted when the checkbox loses focus.

Slots

Learn more about slots.

Name	Description
`default`	The default slot for the label text.
`checked-icon`	The icon to display when the checkbox is checked.
`indeterminate-icon`	The icon to display when the checkbox is in an indeterminate state.

Internationalization

Learn more about internationalization.

Key	Description
`checkbox.aria-label`	The default `aria-label` text for checkbox.

CSS Parts

Learn more about CSS Parts.

Name	Description	Selector
`wrapper`	The wrapper element around the checkbox.	`::part(wrapper)`
`base`	The main label element that contains the checkbox input and visual.	`::part(base)`
`input`	The native checkbox input element.	`::part(input)`
`visual`	The visual representation of the checkbox.	`::part(visual)`
`checked-icon`	The icon displayed when the checkbox is checked.	`::part(checked-icon)`
`indeterminate-icon`	The icon displayed when the checkbox is in an indeterminate state.	`::part(indeterminate-icon)`
`label`	The label text element.	`::part(label)`
`invalid`	The error message element displayed when the checkbox is in an invalid state.	`::part(invalid)`
`hint`	The hint text element displayed below the checkbox.	`::part(hint)`

CSS Custom Properties

Name	Description	Default
`--afp-checkbox-field-disabled-opacity`	The opacity applied to the checkbox when it is disabled.	`0.5`
`--afp-checkbox-label-disabled-opacity`	The opacity applied to the checkbox label when it is disabled.	`0.5`
`--afp-checkbox-background`	The background color of the checkbox.	`--afp-color-neutral-fill-loud`
`--afp-checkbox-color`	The border color of a regular checkbox.	`--afp-color-neutral-text-loud`
`--afp-input-error-border-color`	The border color of the checkbox in the invalid/error state.	`--afp-color-error-500`

Dependencies

The component automatically brings in the listed items, including any nested dependencies that may exist.

Component	CSS Part Prefix
afp-icon	`checked-icon` - The icon displayed when the checkbox is checked. `indeterminate-icon` - The icon displayed when the checkbox is in an indeterminate state.

Importing

Using the bundle is the recommended method to include components. If you’d rather handle imports manually, you can use the code examples below.

import '@afp-design-system/core/dist/components/checkbox/checkbox.js';