> To build a Wix site agentically, or add Wix features like bookings or a store to a site you already have, follow https://www.wix.com/headless/skill.md
> 
> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - If a reference page seems to be missing its schema (parameters, return types, or type definitions), append `?schema=true` to its `.md` URL (e.g. `https://dev.wix.com/docs/contexts/contexts/stores/category-info/use-category-info-context.md?schema=true`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: TagList Component

## Article: TagList Component

## Article Link: https://dev.wix.com/docs/wix-design-system/components/lists/table/tag-list-component.md

## Article Content:

# TagList

_Components/Lists/Table_

Interactive docs page: <https://wix-pages.com/design-system-documentation/#/component/taglist>

## Overview

```jsx
() => {
  const [currentTags, setTags] = React.useState([
    { id: '1', children: 'In Stock' },
    { id: '2', children: 'Jeans' },
  ]);

  const clearAll = () => setTags([]);
  const removeTag = (tagId) =>
    setTags(currentTags.filter(({ id }) => id !== tagId));

  return (
    <Box align="center">
      <TagList
        tags={currentTags}
        actionButton={
          currentTags.length
            ? { label: 'Clear All', onClick: clearAll }
            : undefined
        }
        onTagRemove={removeTag}
      />
    </Box>
  );
};
```

Tag lists are groups of tag and button components. They show active keywords or filters applied to a data table.

### Do

- Display a summary of applied filters in a table.
- Control the applied filters individually or all at once.

### Don't

- Don't use tag lists outside of the `<Table.SubToolbar/>` component.
- Don't use tag lists to indicate the status or category of an item. Use `<Badge/>` instead.

### Feature examples

#### Structure

A tag list consists of any number of tags followed by 2 action buttons:

- Use `toggleMoreButton` to expand/collapse the list.
- Use `actionButton` to control bulk list actions (e.g., Clear All).

Both buttons are optional. The order of the tags and buttons is fixed.

```jsx
<TagList
  tags={[
    { id: '1', children: 'Tag 1' },
    { id: '2', children: 'Tag 2' },
    { id: '3', children: 'Tag 3' },
    { id: '4', children: 'Tag 4' },
    { id: '5', children: 'Tag 5' },
  ]}
  toggleMoreButton={(amountOfHiddenTags, isExpanded) => ({
    label: isExpanded ? 'Show Less' : `+${amountOfHiddenTags} More`,
    tooltipContent: !isExpanded && 'Show More',
  })}
  actionButton={{ label: 'Action Button' }}
  onTagRemove={() => {}}
/>;
```

#### Size

Control the size of entire tag lists with `size` prop:

- Use `tiny` in dense spaces where a `small` list does not fit.
- Use `small` (default) in all default cases.
- Use `medium` in bigger layouts.
- Use `large` when tag lists need to be emphasized.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <StorybookComponents.Stack>
    <TagList
      size="tiny"
      tags={[{ id: '1', children: 'Tiny' }]}
      actionButton={{ label: 'Tiny' }}
      onTagRemove={() => {}}
    />
  </StorybookComponents.Stack>
  <StorybookComponents.Stack>
    <TagList
      tags={[{ id: '1', children: 'Small' }]}
      actionButton={{ label: 'Small' }}
      onTagRemove={() => {}}
    />
  </StorybookComponents.Stack>
  <StorybookComponents.Stack>
    <TagList
      size="medium"
      tags={[{ id: '1', children: 'Medium' }]}
      actionButton={{ label: 'Medium' }}
      onTagRemove={() => {}}
    />
  </StorybookComponents.Stack>

  <StorybookComponents.Stack>
    <TagList
      size="large"
      tags={[{ id: '1', children: 'Large' }]}
      actionButton={{ label: 'Large' }}
      onTagRemove={() => {}}
    />
  </StorybookComponents.Stack>
</StorybookComponents.Stack>;
```

#### Tag props

Customize individual tags with `<Tag/>` component props:

- Set the color of a tag using `theme`.
- Display a thumbnail inside a tag using `thumb.`
- Switch tag to a disabled state using `disabled`.
- Show or hide a close button on the right side of a tag using `removable` .
- Set a max tag width in px using `maxWidth`. If a label is longer, text gets truncated with ellipses.

See `<Tag/>` for a full prop description.

```jsx
<TagList
  tags={[
    {
      id: '1',
      theme: 'success',
      children: 'theme',
    },
    {
      id: '2',
      children: 'thumb',
      thumb: (
        <Avatar
          imgProps={{
            src: 'AvatarExample1.jpg',
          }}
          size="size18"
        />
      ),
    },
    {
      id: '3',
      disabled: true,
      children: 'disabled',
    },
    {
      id: '4',
      removable: false,
      children: 'removable',
    },
    {
      id: '5',
      maxWidth: 100,
      children: 'maxWidth',
    },
  ]}
  maxVisibleTags={5}
  onTagRemove={() => {}}
/>;
```

#### Toggle more button props

Control the appearance of `toggleMoreButton` with `skin` and `priority` props.

Set its skin as `standard` and priority as `secondary` to emphasize the component `actionButton` on the left.

```jsx
<TagList
  tags={[
    { id: '1', children: 'Tag 1' },
    { id: '2', children: 'Tag 2' },
    { id: '3', children: 'Tag 3' },
    { id: '4', children: 'Tag 4' },
    { id: '5', children: 'Tag 5' },
  ]}
  maxVisibleTags={3}
  actionButton={{ label: 'Action Button' }}
  toggleMoreButton={(amountOfHiddenTags, isExpanded) => ({
    label: isExpanded ? 'Show Less' : `+${amountOfHiddenTags} More`,
    tooltipContent: !isExpanded && 'Show More',
    skin: 'standard',
    priority: 'secondary',
  })}
  onTagRemove={() => {}}
/>;
```

#### Max visible tags

Limit the number of visible tags with `maxVisibleTags` prop (default is 3).

Use it to fit a tag list in one line and keep the layout compact.

If tags surpass the limit, give an option to expand the full list with `toggleMoreButton` prop.

Note that if the component width is larger than the parent container, it will display on multiple lines when expanded.

```jsx
<TagList
  tags={[
    { id: '1', children: 'Tag 1' },
    { id: '2', children: 'Tag 2' },
    { id: '3', children: 'Tag 3' },
    { id: '4', children: 'Tag 4' },
    { id: '5', children: 'Tag 5' },
    { id: '6', children: 'Tag 6' },
    { id: '7', children: 'Tag 7' },
    { id: '8', children: 'Tag 8' },
    { id: '9', children: 'Tag 9' },
    { id: '10', children: 'Tag 10' },
    { id: '11', children: 'Tag 11' },
    { id: '12', children: 'Tag 12' },
  ]}
  maxVisibleTags={3}
  toggleMoreButton={(amountOfHiddenTags, isExpanded) => ({
    label: isExpanded ? 'Show Less' : `+${amountOfHiddenTags} More`,
    tooltipContent: !isExpanded && 'Show More',
  })}
  onTagRemove={() => {}}
/>;
```

#### Initially expanded

Define whether the list is expanded initially with an `initiallyExpanded` prop.

```jsx
() => {
  const tags = [
    { id: '1', children: 'Tag 1' },
    { id: '2', children: 'Tag 2' },
    { id: '3', children: 'Tag 3' },
    { id: '4', children: 'Tag 4' },
    { id: '5', children: 'Tag 5' },
  ];

  const toggleMore = (amountOfHiddenTags, isExpanded) => ({
    label: isExpanded ? 'Show Less' : `+${amountOfHiddenTags} More`,
    tooltipContent: !isExpanded && 'Show More',
  });

  return (
    <StorybookComponents.Stack flexDirection="column">
      <Text size="small">Not Initially Expanded</Text>
      <TagList
        tags={tags}
        initiallyExpanded={false}
        toggleMoreButton={toggleMore}
        onTagRemove={() => {}}
      />
      <Text size="small">Initially Expanded</Text>
      <TagList
        tags={tags}
        initiallyExpanded
        toggleMoreButton={toggleMore}
        onTagRemove={() => {}}
      />
    </StorybookComponents.Stack>
  );
};
```

### Common use case examples

#### Applied filters list

Use a tag list to show which filters are applied in a `<Table/>`.

```jsx
() => {
  const tags = [
    { id: 1, children: 'In Stock' },
    { id: 2, children: 'Accessories' },
  ];

  const initialState = {
    tableData: [],
    selectedInventoryStatusId: 0,
    selectedProductTypeId: 0,
    tags,
    activeSearch: '',
  };
  const [state, setState] = React.useReducer(
    (currentState, newState) => ({ ...currentState, ...newState }),
    initialState,
  );

  const getProductTypeFilterById = (id) =>
    productTypeFilter.find((type) => type.id === id);

  const getInventoryStatusFilterById = (id) =>
    inventoryStatusFilter.find((inventory) => inventory.id === id);

  const filterRecords = ({ inventoryStatusId, productTypeId }) => {
    const inventoryStatus = getInventoryStatusFilterById(inventoryStatusId);
    const productType = getProductTypeFilterById(productTypeId);

    return records.filter((record) => {
      const inventoryStatusFilter =
        !inventoryStatus || record.inventory === inventoryStatus.value;
      const productTypeFilter =
        !productType || record.type === productType.value;

      return inventoryStatusFilter && productTypeFilter;
    });
  };

  React.useEffect(() => {
    setState({
      tableData: filterRecords({ inventoryStatusId: 1, productTypeId: 1 }),
      selectedInventoryStatusId: 1,
      selectedProductTypeId: 1,
    });
  }, []);

  const records = [
    {
      name: `Red Slippers`,
      SKU: '0231664667',
      price: '$14.00',
      inventory: 'In Stock',
      type: 'Accessories',
    },
    {
      name: `Velvet Hat`,
      SKU: '0231664669',
      price: '$23.00',
      inventory: 'In Stock',
      type: 'Accessories',
    },
    {
      name: `Silver Bag`,
      SKU: '0231664667',
      price: '$69.00',
      inventory: 'In Stock',
      type: 'Accessories',
    },
    {
      name: `Orange Socks`,
      SKU: '0231662525',
      price: '$9.00',
      inventory: 'Out of Stock',
      type: 'Accessories',
    },
    {
      name: `Red Socks`,
      SKU: '0231664671',
      price: '$19.00',
      inventory: 'In Stock',
      type: 'Accessories',
    },
    {
      name: `Gold Earrings`,
      SKU: '0231666090',
      price: '$22.00',
      inventory: 'Out of Stock',
      type: 'Accessories',
    },
    {
      name: `Blue Jeans`,
      SKU: '0231664525',
      price: '$59.00',
      inventory: 'In Stock',
      type: 'Clothing',
    },
    {
      name: `Black Jacket`,
      SKU: '0231664000',
      price: '$89.00',
      inventory: 'In Stock',
      type: 'Clothing',
    },
    {
      name: `Black Belt`,
      SKU: '0231664672',
      price: '$19.00',
      inventory: 'In Stock',
      type: 'Accessories',
    },
  ];

  const columns = [
    {
      title: 'Name',
      render: (row) => row.name,
      width: '25%',
    },
    {
      title: 'SKU',
      render: (row) => row.SKU,
      width: '25%',
    },
    {
      title: 'Price',
      render: (row) => row.price,
      width: '25%',
    },
    {
      title: 'Inventory',
      render: (row) => row.inventory,
      width: '25%',
    },
  ];
  const inventoryStatusFilter = [
    { id: 1, value: 'In Stock' },
    { id: 2, value: 'Out of Stock' },
  ];
  const productTypeFilter = [
    { id: 1, value: 'Accessories' },
    { id: 2, value: 'Clothing' },
  ];

  const clearAll = () =>
    setState({
      tags: [],
      selectedInventoryStatusId: 0,
      selectedProductTypeId: 0,
      tableData: records,
    });

  const removeTag = (tagId) => {
    const tags = state.tags.filter(({ id }) => id !== tagId);

    const inventoryStatusId = tags.find((tag) => tag.id === 1)
      ? state.selectedInventoryStatusId
      : 0;
    const productTypeId = tags.find((tag) => tag.id === 2)
      ? state.selectedProductTypeId
      : 0;

    setState({
      tags,
      tableData: filterRecords({
        inventoryStatusId,
        productTypeId,
      }),
      selectedInventoryStatusId: inventoryStatusId,
      selectedProductTypeId: productTypeId,
    });
  };

  const onOptionChange = ({
    inventoryStatusId = state.selectedInventoryStatusId,
    productTypeId = state.selectedProductTypeId,
  }) => {
    setState({
      selectedProductTypeId: productTypeId,
      selectedInventoryStatusId: inventoryStatusId,
      tableData: filterRecords({
        inventoryStatusId,
        productTypeId,
      }),
      tags: filterTags({ inventoryStatusId, productTypeId }),
    });
  };

  const filterTags = ({ inventoryStatusId, productTypeId }) => {
    const inventoryStatus = getInventoryStatusFilterById(inventoryStatusId);
    const productType = getProductTypeFilterById(productTypeId);
    const tags = [];

    inventoryStatus && tags.push({ id: 1, children: inventoryStatus.value });
    productType && tags.push({ id: 2, children: productType.value });

    return tags;
  };

  const getFilteredData = () => {
    if (!state.activeSearch) {
      return state.tableData;
    }

    return state.tableData.filter(({ name, sku, price, inventory, type }) => {
      const searchData = [name, sku, price, inventory, type]
        .join(' ')
        .toLowerCase();
      const searchQuery = state.activeSearch.trim().toLowerCase();
      return !searchQuery || searchData.indexOf(searchQuery) !== -1;
    });
  };

  return (
    <Card>
      <TableToolbar>
        <TableToolbar.ItemGroup position="start">
          <TableToolbar.Item>
            <TableToolbar.Title>Products</TableToolbar.Title>
          </TableToolbar.Item>
        </TableToolbar.ItemGroup>
        <TableToolbar.ItemGroup position="end">
          <TableToolbar.Item>
            <Box gap={2} verticalAlign="middle">
              <Text>Filter by</Text>
              <Dropdown
                size="small"
                placeholder="Inventory status"
                border="round"
                options={inventoryStatusFilter}
                selectedId={state.selectedInventoryStatusId}
                onSelect={(option) =>
                  onOptionChange({ inventoryStatusId: option.id })
                }
              />
              <Dropdown
                size="small"
                placeholder="Type"
                border="round"
                options={productTypeFilter}
                selectedId={state.selectedProductTypeId}
                onSelect={(option) =>
                  onOptionChange({ productTypeId: option.id })
                }
              />
            </Box>
          </TableToolbar.Item>
          <TableToolbar.Item>
            <Box width="200">
              <Search
                value={state.activeSearch}
                onChange={(e) => setState({ activeSearch: e.target.value })}
                onClear={() => setState({ activeSearch: '' })}
              />
            </Box>
          </TableToolbar.Item>
        </TableToolbar.ItemGroup>
      </TableToolbar>
      {state.tags.length ? (
        <Table.SubToolbar>
          <Box align="space-between" verticalAlign="middle">
            <Cell>
              <FormField label="Filtered by:" labelPlacement="left">
                <TagList
                  tags={state.tags}
                  actionButton={{ label: 'Clear All', onClick: clearAll }}
                  onTagRemove={removeTag}
                />
              </FormField>
            </Cell>
            <Cell>
              <Button
                size="tiny"
                skin="inverted"
                prefixIcon={<Icons.FavoriteSmall />}
              >
                Save Filter
              </Button>
            </Cell>
          </Box>
        </Table.SubToolbar>
      ) : null}
      <Table data={getFilteredData()} columns={columns}>
        <Table.Content />
      </Table>
    </Card>
  );
};
```

## Code

```jsx
import { TagList } from '@wix/design-system';
```

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `actionButton` | `TagListActionButtonProps` | — | Defines the label of an action button and its onClick function. |
| `dataHook` | `string` | — | Applies a data-hook HTML attribute to be used in the tests. |
| `initiallyExpanded` | `boolean` | `false` | Defines whether the list is: - initially expanded (shows all tags) - or collapsed (shows tags up to the max visible number) |
| `maxVisibleTags` | `number` | `3` | Sets an amount of tags to show before expanding. |
| `onTagRemove` | `(id: string) => void` | — | Defines a callback function that passes an `id` property as a parameter when removing a tag. |
| `overflowMode` | `"collapse" \| TagListCollapseOverflowConfig` | — | Controls how tags that don't fit the container are handled. - `'collapse'` — tags auto-fit the container width and the rest collapse into a `+N` chip whose tooltip lists their labels. - Object form (`{ type: 'collapse', renderTag, overflowTooltipContent }`) — same behavior with per-feature configuration. When set, `maxVisibleTags`, `toggleMoreButton`, and `initiallyExpanded` are ignored. Costly for very large lists (each tag is rendered twice for measurement); prefer manual collapse via `maxVisibleTags` for large tag arrays. Tags collapsed into the `+N` chip aren't interactive — their labels appear in the chip's tooltip, but their remove buttons are unreachable. For removable tags prefer `maxVisibleTags` + `toggleMoreButton`, which lets users expand the list and reach every tag. |
| `size` | `"small" \| "tiny" \| "medium" \| "large"` | `'small'` | Sets the size of a component. |
| `tags` *(required)* | `TagListTag[]` | — | Lists all component's tags and its properties. |
| `toggleMoreButton` | `(amountOfHiddenTags: number, isExpanded: boolean) => ToggleMoreButtonProps` | — | Defines a function which provides props for the ToggleMoreButton. ##### toggleMoreButton signature is: `function(amountOfHiddenTags: number, isExpanded: boolean) => ToggleMoreButtonProps` ##### ToggleMoreButtonProps: * `label`: string * `tooltipContent`: node * `tooltipProps`: TooltipCommonProps |

## Testkit

Import the driver matching your test environment:

```jsx
// UniDriver
import { TagListUniDriver } from '@wix/design-system/dist/testkit/unidriver';

// Vanilla
import { TagListTestkit } from '@wix/design-system/dist/testkit';

// Puppeteer
import { TagListTestkit } from '@wix/design-system/dist/testkit/puppeteer';

// Testing Library
import { TagListTestkit } from '@wix/design-system/dist/testkit/testing-library';
```

### Driver methods

| Method | Description |
| --- | --- |
| `actionButtonLabel` | Get the action button label. |
| `clickActionButton` | Click action button. |
| `actionButtonExists` | Get if action button exists. |
| `toggleMoreButtonLabel` | Get the toggle more button label. |
| `clickToggleMoreButton` | Click toggle more button |
| `toggleMoreButtonExists` | Get if toggle more button exists. |
| `removeTag` | Remove tag by id. |
| `overflowChipExists` | Get if the responsive `+N` overflow chip exists. |
| `overflowChipLabel` | Get the responsive `+N` overflow chip text (e.g. `"+3"`). |
| `focusOverflowChip` | Focus the responsive `+N` overflow chip. |
| `isOverflowChipFocused` | Whether the responsive `+N` overflow chip is currently focused. |
| `exists` | Checks whether the component found with the given data hook. |
| `element` | Gets the component root element. |
| `click` | Clicks on the component root element. |
| `base` | Returns UniDriver for the base element. |

## Changelog

- **1.340.0** (2026-10-21) — maintenance release, no component-specific changes
- **1.339.0** (2026-10-19) — maintenance release, no component-specific changes
- **1.338.0** (2026-10-15) — maintenance release, no component-specific changes
- **1.330.0** (2026-09-28) — maintenance release, no component-specific changes
- **1.329.0** (2026-09-24) — maintenance release, no component-specific changes
- **1.328.0** (2026-09-22) — maintenance release, no component-specific changes
- **1.327.0** (2026-09-21) — maintenance release, no component-specific changes
- **1.325.0** (2026-09-17) — maintenance release, no component-specific changes
- **1.323.0** (2026-09-10) — maintenance release, no component-specific changes
- **1.310.0** (2026-08-10) — maintenance release, no component-specific changes
- **1.299.0** (2026-07-17) — breaking: increase gap between tags and clear button (Harmony & Harmony Dark themes) ([#16556](invalid-url)) — has visual changes
- **1.296.0** (2026-07-08) — feat: harmony restyle and tiny size ([#16495](invalid-url)) — has visual changes
- **1.292.0** (2026-06-22) — maintenance release, no component-specific changes
- **1.291.0** (2026-06-19) — maintenance release, no component-specific changes
- **1.284.0** (2026-06-04) — feat: add responsive overflow mode with +N chip ([#16264](invalid-url)) — has visual changes
- **1.266.0** (2026-04-07) — maintenance release, no component-specific changes
- **1.260.0** (2026-03-17) — maintenance release, no component-specific changes
- **1.254.0** (2026-02-03) — maintenance release, no component-specific changes
- **1.244.0** (2026-01-02) — feat: focus on Tag removal ([#15734](invalid-url))
- **1.241.0** (2025-12-17) — maintenance release, no component-specific changes
- **1.169.0** (2025-03-10) — maintenance release, no component-specific changes
- **1.149.1** (2024-12-20) — maintenance release, no component-specific changes
- **1.115.0** (2024-07-17) — maintenance release, no component-specific changes
- **1.98.0** (2024-03-15) — maintenance release, no component-specific changes
- **1.93.0** (2024-02-08) — maintenance release, no component-specific changes
- **1.92.1** (2024-02-05) — maintenance release, no component-specific changes