Chip Group (ALPHA)

BusinessEnterprise

Alpha feature: invite only

Responsive Widgets are in alpha and available by invitation only on Business and Enterprise plans. Behavior and properties may change. To request access, open a support ticket and name the feature Responsive Widgets (ALPHA).

The Chip Group widget shows a set of chips that users act on. Use it for filter bars, lists of tokens that users can remove, or quick actions. For tags that are only for display, use the TagGroup widget.

The Variant property sets how the chips behave:

Variant	What users can do	Event
Filter	Select one or more chips.	onSelectionChange
Input	Remove chips. Optionally add chips with a + button.	onRemove, onAdd
Assist	Tap a chip to run an action. Chips never stay selected.	onChipClick
Suggestion	Tap a chip to run an action. Chips never stay selected.	onChipClick

Widget type: WDS_CHIP_GROUP_WIDGET

Chip Group widget

Content properties

These properties appear in the Content tab of the property pane.

Basic

Variant string

Sets how the chips behave. Options: Assist, Filter (default), Input, Suggestion. See the table at the top of this page.

You set this property in the property pane only. You cannot bind it to data. Other properties and events show or hide based on the variant.

Selection mode string

Sets how many chips users can select at once. Options: None, Single, Multi (default).

You set this property in the property pane only. You cannot bind it to data.

This property shows only when Variant is Filter.

Data

Options array

Sets the chips to show, as an array of objects with a label, a value, and an optional icon. The icon is the name of an icon from the icon set. The widget ignores icon names it does not know.

Example:

[
  { "label": "Design", "value": "DESIGN", "icon": "palette" },
  { "label": "Engineering", "value": "ENG", "icon": "code" },
  { "label": "Marketing", "value": "MKT" }
]

The array must follow these rules, or the property pane shows an error:

• Each item needs a label and a value.
• Each value must be a string or a number, and must be unique.
• All value fields must have the same type.

The label always shows as text, never as HTML. When the array has no chips, the widget shows "No chips to display."

Default selected values array

Sets the values of the chips that are selected when the widget loads. Default: ["DESIGN"].

Example:

["DESIGN", "ENG"]

When this value changes, the selection resets to the new value.

This property shows only when Variant is Filter and Selection mode is not None.

General

Removable boolean

Lets users remove chips. Default: on.

This property shows only when Variant is Input.

Show add button boolean

Shows a + button after the chips. Use the onAdd event to decide what it does. Default: off.

This property shows only when Variant is Input.

Overflow string

Sets what happens when the chips do not fit on one line. Options:

• Wrap (default): chips flow onto new lines.
• Scroll: chips stay on one line, and users scroll sideways.

You set this property in the property pane only. You cannot bind it to data.

Visible boolean

Controls whether the widget is visible. Default: on.

Disabled boolean

Stops users from using the chips and the + button. Default: off.

Animate loading boolean

Controls the loading animation of the widget. Default: on.

Reference properties

Reference properties let you read the widget's state in bindings and code, for example {{ChipGroup1.selectedValues}}. You cannot set them directly.

selectedValues array

The values of the selected chips (Filter variant).

Example:

{{ChipGroup1.selectedValues}}

selectedValue string | number

The value of the selected chip when Selection mode is Single. In other modes it is undefined.

Example:

{{ChipGroup1.selectedValue}}

value string | number | array

The selection in a form-friendly shape. When Selection mode is Single, it holds one value. Otherwise, it holds the same array as selectedValues.

Example:

{{ChipGroup1.value}}

options array

The full options array set on the widget, including chips that users removed.

Example:

{{ChipGroup1.options}}

chips array

The chips on screen now: options without the chips that users removed (Input variant).

Example:

{{ChipGroup1.chips}}

removedValues array

The values of the chips that users removed (Input variant).

Example:

{{ChipGroup1.removedValues}}

isDirty boolean

Shows whether users have selected or removed a chip since the widget loaded, or since Default selected values last changed.

Example:

{{ChipGroup1.isDirty}}

isVisible boolean

Shows whether the widget is visible.

Example:

{{ChipGroup1.isVisible}}

Methods

Methods let you change the widget's properties from code, for example in a JS Object.

setVisibility (param: boolean): Promise

Shows or hides the widget.

Example:

ChipGroup1.setVisibility(false)

setDisabled (param: boolean): Promise

Turns the chips on or off.

Example:

ChipGroup1.setDisabled(true)

setSelectedValues (param: array): Promise

Sets which chips are selected (Filter variant). Pass an array of chip values.

Example:

ChipGroup1.setSelectedValues(["ENG"])

Events

onSelectionChange

Runs when users change the selected chips. Read the new selection from selectedValues.

This event shows only when Variant is Filter and Selection mode is not None.

onChipClick

Runs when users tap a chip. The value of the tapped chip is available as {{chipValue}} inside the action.

This event shows only when Variant is Assist or Suggestion.

onRemove

Runs when users remove a chip. The removed value is available as {{removedValue}} inside the action, and all values removed by that action as {{removedValues}}. A removed chip is also taken out of the selection.

This event shows only when Variant is Input and Removable is on.

onAdd

Runs when users click the + button.

This event shows only when Variant is Input and Show add button is on.