TagList

Components/Lists/Table

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

Overview

Copy

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.

Copy

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.
Copy

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.

Copy

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.

Copy

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.

Copy

Initially expanded

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

Copy

Common use case examples

Applied filters list

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

Copy

Code

Copy

Props

NameTypeDefaultDescription
actionButtonTagListActionButtonProps—Defines the label of an action button and its onClick function.
dataHookstring—Applies a data-hook HTML attribute to be used in the tests.
initiallyExpandedbooleanfalseDefines whether the list is: - initially expanded (shows all tags) - or collapsed (shows tags up to the max visible number)
maxVisibleTagsnumber3Sets 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:

Copy

Driver methods

MethodDescription
actionButtonLabelGet the action button label.
clickActionButtonClick action button.
actionButtonExistsGet if action button exists.
toggleMoreButtonLabelGet the toggle more button label.
clickToggleMoreButtonClick toggle more button
toggleMoreButtonExistsGet if toggle more button exists.
removeTagRemove tag by id.
overflowChipExistsGet if the responsive +N overflow chip exists.
overflowChipLabelGet the responsive +N overflow chip text (e.g. "+3").
focusOverflowChipFocus the responsive +N overflow chip.
isOverflowChipFocusedWhether the responsive +N overflow chip is currently focused.
existsChecks whether the component found with the given data hook.
elementGets the component root element.
clickClicks on the component root element.
baseReturns 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) — has visual changes
  • 1.296.0 (2026-07-08) — feat: harmony restyle and tiny size (#16495) — 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) — 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)
  • 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

Last updated: 29 October 2026

Did this help?