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

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 | | :----------- | :----------------------------- | :------ | :------------------------------------------------------------------------------------------------------------ | | testID | string | — | Test ID for testing frameworks. On web this renders as data-testid; on React Native it renders as testID. | | 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