Checkbox

A cross-platform React checkbox component with label, description, indeterminate state, and validation support. Works on both React (web) and React Native.

Installation

npm install @xsolla/xui-checkbox

Demo

Basic Checkbox

import * as React from 'react';
import { Checkbox } from '@xsolla/xui-checkbox';

export default function BasicCheckbox() {
  const [checked, setChecked] = React.useState(false);

  return (
    <Checkbox
      checked={checked}
      onChange={(e) => setChecked(e.target.checked)}
    >
      Accept terms and conditions
    </Checkbox>
  );
}

Checkbox with Description

import * as React from 'react';
import { Checkbox } from '@xsolla/xui-checkbox';

export default function CheckboxWithDescription() {
  const [checked, setChecked] = React.useState(false);

  return (
    <Checkbox
      checked={checked}
      onChange={(e) => setChecked(e.target.checked)}
      description="You will receive notifications about updates and promotions"
    >
      Subscribe to newsletter
    </Checkbox>
  );
}

Checkbox Sizes

import * as React from 'react';
import { Checkbox } from '@xsolla/xui-checkbox';

export default function CheckboxSizes() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
      <Checkbox size="sm">Small checkbox</Checkbox>
      <Checkbox size="md">Medium checkbox (default)</Checkbox>
      <Checkbox size="lg">Large checkbox</Checkbox>
      <Checkbox size="xl">Extra large checkbox</Checkbox>
    </div>
  );
}

Indeterminate State

import * as React from 'react';
import { Checkbox } from '@xsolla/xui-checkbox';

export default function IndeterminateCheckbox() {
  const [items, setItems] = React.useState([
    { id: 1, label: 'Item 1', checked: true },
    { id: 2, label: 'Item 2', checked: false },
    { id: 3, label: 'Item 3', checked: true },
  ]);

  const allChecked = items.every((item) => item.checked);
  const someChecked = items.some((item) => item.checked);

  const handleSelectAll = () => {
    setItems(items.map((item) => ({ ...item, checked: !allChecked })));
  };

  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
      <Checkbox
        checked={allChecked}
        indeterminate={someChecked && !allChecked}
        onChange={handleSelectAll}
      >
        Select all
      </Checkbox>
      <div style={{ marginLeft: 24, display: 'flex', flexDirection: 'column', gap: 8 }}>
        {items.map((item) => (
          <Checkbox
            key={item.id}
            checked={item.checked}
            onChange={(e) => {
              setItems(items.map((i) =>
                i.id === item.id ? { ...i, checked: e.target.checked } : i
              ));
            }}
          >
            {item.label}
          </Checkbox>
        ))}
      </div>
    </div>
  );
}

Anatomy

Import the component and use it directly:

import { Checkbox } from '@xsolla/xui-checkbox';

<Checkbox
  checked={checked}             // Controlled checked state
  onChange={handleChange}       // Change handler
  indeterminate={false}         // Indeterminate/mixed state
  size="md"                      // Size variant
  description="Help text"       // Description below label
  errorMessage="Error text"     // Error message
  disabled={false}              // Disabled state
>
  Label text
</Checkbox>

Examples

Error State

import * as React from 'react';
import { Checkbox } from '@xsolla/xui-checkbox';

export default function ErrorCheckbox() {
  return (
    <Checkbox
      checked={false}
      errorMessage="You must accept the terms to continue"
    >
      I accept the terms and conditions
    </Checkbox>
  );
}

Disabled Checkbox

import * as React from 'react';
import { Checkbox } from '@xsolla/xui-checkbox';

export default function DisabledCheckbox() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
      <Checkbox disabled>Disabled unchecked</Checkbox>
      <Checkbox disabled checked>Disabled checked</Checkbox>
      <Checkbox disabled indeterminate>Disabled indeterminate</Checkbox>
    </div>
  );
}

Form Integration

import * as React from 'react';
import { Checkbox } from '@xsolla/xui-checkbox';
import { Button } from '@xsolla/xui-button';

export default function FormCheckbox() {
  const [preferences, setPreferences] = React.useState({
    marketing: false,
    updates: true,
    newsletter: false,
  });

  const handleChange = (key: string) => (e: { target: { checked: boolean } }) => {
    setPreferences((prev) => ({ ...prev, [key]: e.target.checked }));
  };

  return (
    <form onSubmit={(e) => { e.preventDefault(); console.log(preferences); }}>
      <div style={{ display: 'flex', flexDirection: 'column', gap: 12 }}>
        <Checkbox
          name="marketing"
          checked={preferences.marketing}
          onChange={handleChange('marketing')}
        >
          Receive marketing emails
        </Checkbox>
        <Checkbox
          name="updates"
          checked={preferences.updates}
          onChange={handleChange('updates')}
        >
          Receive product updates
        </Checkbox>
        <Checkbox
          name="newsletter"
          checked={preferences.newsletter}
          onChange={handleChange('newsletter')}
        >
          Subscribe to newsletter
        </Checkbox>
        <Button type="submit">Save Preferences</Button>
      </div>
    </form>
  );
}

API Reference

Checkbox

The main checkbox component with label support.

Checkbox Props:

| Prop | Type | Default | Description | | :--- | :--- | :------ | :---------- | | children | ReactNode | - | Label content displayed next to the checkbox. | | checked | boolean | false | Whether the checkbox is checked. | | indeterminate | boolean | false | Whether to show indeterminate (mixed) state. | | size | "sm" \| "md" \| "lg" \| "xl" | "md" | Size of the checkbox. | | disabled | boolean | false | Whether the checkbox is disabled. | | description | string | - | Description text displayed below the label. | | errorMessage | string | - | Error message displayed below (shows error styling). | | error | boolean | false | Show error styling without message. | | name | string | - | HTML name attribute for form submission. | | value | string | - | HTML value attribute for form submission. | | onChange | (e: { target: { checked: boolean; name?: string; value?: string } }) => void | - | Change event handler. | | id | string | - | HTML id attribute. | | aria-label | string | - | Accessible label for screen readers. |

Checkbox Ref Methods:

| Method | Description | | :----- | :---------- | | focus() | Programmatically focus the checkbox. | | blur() | Programmatically blur the checkbox. |

Size Configuration:

| Size | Checkbox | Icon | Gap | Label font/line | Description font/line | | :--- | :------- | :--- | :-- | :-------------- | :-------------------- | | sm | 16px | 10px | 6px | 14 / 16 | 12 / 14 | | md | 18px | 12px | 8px | 16 / 18 | 14 / 16 | | lg | 20px | 14px | 10px | 18 / 20 | 16 / 18 | | xl | 24px | 16px | 12px | 20 / 22 | 18 / 20 |

Frame border is 1px with 4px radius at every size.

Accessibility

• role="checkbox" with aria-checked reflecting state ("true", "false", "mixed").
• Keyboard: Tab to focus, Space or Enter to toggle.
• Visible focus ring: 2px solid border.brand outline with 2px offset.
• aria-invalid set when error or errorMessage is supplied.
• aria-describedby links the label to description and error nodes when present.
• aria-labelledby links the control to its visible label; aria-label is used when there is no visible label.
• Disabled checkboxes use aria-disabled="true" and are removed from the tab order.