Checkbox Tag Group

A cross-platform React component for selecting multiple options displayed as tag-style checkboxes. Supports controlled and uncontrolled modes with validation. Works on both React (web) and React Native.

Installation

npm install @xsolla/xui-checkbox-tag-group
# or
yarn add @xsolla/xui-checkbox-tag-group

Demo

Basic Usage

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

const options = [
  { label: 'Action', value: 'action' },
  { label: 'RPG', value: 'rpg' },
  { label: 'Strategy', value: 'strategy' },
];

export default function BasicCheckboxTagGroup() {
  return (
    <CheckboxTagGroup
      options={options}
      defaultValue={['action']}
      aria-label="Game genres"
    />
  );
}

Controlled

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

const options = [
  { label: 'Action', value: 'action' },
  { label: 'RPG', value: 'rpg' },
  { label: 'Strategy', value: 'strategy' },
];

export default function ControlledCheckboxTagGroup() {
  const [values, setValues] = React.useState(['action']);

  return (
    <CheckboxTagGroup
      options={options}
      value={values}
      onChange={setValues}
      aria-label="Game genres"
    />
  );
}

Sizes

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

const options = [
  { label: 'Item 1', value: 'item1' },
  { label: 'Item 2', value: 'item2' },
  { label: 'Item 3', value: 'item3' },
];

export default function CheckboxTagGroupSizes() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: 24 }}>
      <CheckboxTagGroup options={options} size="xl" defaultValue={['item1']} aria-label="XL tags" />
      <CheckboxTagGroup options={options} size="lg" defaultValue={['item1']} aria-label="LG tags" />
      <CheckboxTagGroup options={options} size="md" defaultValue={['item1']} aria-label="MD tags" />
      <CheckboxTagGroup options={options} size="sm" defaultValue={['item1']} aria-label="SM tags" />
    </div>
  );
}

Anatomy

Import the component and use it directly:

import { CheckboxTagGroup } from '@xsolla/xui-checkbox-tag-group';

<CheckboxTagGroup
  options={options}               // Array of { label, value, disabled? }
  value={selectedValues}          // Controlled selected values
  defaultValue={['item1']}       // Default values (uncontrolled)
  onChange={handleChange}         // Callback with new values array
  size="md"                       // Size variant
  disabled={false}                // Disable all options
  errorMessage="Select at least one" // Error message
  aria-label="Filter options"    // Accessible label
/>

Examples

With Error

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

const options = [
  { label: 'Action', value: 'action' },
  { label: 'RPG', value: 'rpg' },
  { label: 'Strategy', value: 'strategy' },
];

export default function ErrorCheckboxTagGroup() {
  return (
    <CheckboxTagGroup
      options={options}
      errorMessage="Please select at least one genre"
      aria-label="Game genres"
    />
  );
}

With Disabled Option

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

const options = [
  { label: 'Action', value: 'action' },
  { label: 'RPG (coming soon)', value: 'rpg', disabled: true },
  { label: 'Strategy', value: 'strategy' },
];

export default function DisabledOptionCheckboxTagGroup() {
  return (
    <CheckboxTagGroup
      options={options}
      defaultValue={['action']}
      aria-label="Game genres"
    />
  );
}

Fully Disabled

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

const options = [
  { label: 'Action', value: 'action' },
  { label: 'RPG', value: 'rpg' },
  { label: 'Strategy', value: 'strategy' },
];

export default function DisabledCheckboxTagGroup() {
  return (
    <CheckboxTagGroup
      options={options}
      defaultValue={['action']}
      disabled
      aria-label="Game genres"
    />
  );
}

API Reference

CheckboxTagGroup

Props:

| Prop | Type | Default | Description | | :--- | :--- | :------ | :---------- | | options | CheckboxTagGroupItem[] | - | Array of options to display. | | value | string[] | - | Controlled selected values. | | defaultValue | string[] | [] | Default selected values (uncontrolled). | | onChange | (values: string[]) => void | - | Callback when selection changes. | | size | "xl" \| "lg" \| "md" \| "sm" | "md" | Size of the tag items. | | disabled | boolean | false | Disable all options. | | errorMessage | string | - | Error message displayed below the group. | | aria-label | string | - | Accessible label for the group. |

CheckboxTagGroupItem

| Prop | Type | Default | Description | | :--- | :--- | :------ | :---------- | | label | string | - | Display text for the option. | | value | string | - | Value identifier for the option. | | disabled | boolean | false | Disable this specific option. |

Accessibility

• Uses role="group" with aria-label on the container
• Each option has role="checkbox" with aria-checked
• aria-disabled set on disabled options
• aria-describedby links to error message when present
• Error messages use role="alert" for screen reader announcement
• Keyboard navigation with Tab between options and Space/Enter to toggle