# Checkbox Tag Group

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

## Installation

```bash
npm install @xsolla/xui-checkbox-tag-group
```

## Demo

### Basic Usage

```tsx
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

```tsx
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"
    />
  );
}
```

### Single Selection

```tsx
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 SingleSelectCheckboxTagGroup() {
  const [values, setValues] = React.useState<string[]>(["action"]);

  return (
    <CheckboxTagGroup
      options={options}
      value={values}
      onChange={setValues}
      selectionMode="single"
      aria-label="Primary genre"
    />
  );
}
```

### Sizes

```tsx
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:

```jsx
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
  selectionMode="multiple" // "single" | "multiple" (default "multiple")
  disabled={false} // Disable all options
  errorMessage="Select at least one" // Error message
  aria-label="Filter options" // Accessible label
/>;
```

## Examples

### With Error

```tsx
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

```tsx
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

```tsx
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.                                                                                        |
| selectionMode | `"single" \| "multiple"`       | `"multiple"` | Selection mode. In `"single"` mode at most one tag is selected at a time; selecting a new tag deselects the previous one. |
| 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

- In `"multiple"` mode the container uses `role="group"` and each option uses `role="checkbox"` with `aria-checked`
- In `"single"` mode the container uses `role="radiogroup"` and each option uses `role="radio"` with `aria-checked`
- `aria-label` is applied to the container
- `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