Chip Group

<sl-chip-group> | SlChipGroup
Since 2.2.0 stable

Chip groups are used to group multiple chips so they function as a single form control.

Text Text Text 
<sl-chip-group>
  <sl-chip>Text</sl-chip>
  <sl-chip active>Text</sl-chip>
  <sl-chip disabled>Text</sl-chip>
</sl-chip-group>

Examples

Stacked

Default is inline layout, use stacked attribute for a stacked layout.

Text Text Text
Text Text Text 
<sl-chip-group label="Label" help-text="This is optional help text">
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip disabled>Text</sl-chip>
</sl-chip-group>
<br/>
<sl-chip-group label="Label" help-text="This is optional help text" stacked>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip disabled>Text</sl-chip>
</sl-chip-group>

Overflow

When chips exceed more than horizontal space allows, wrap to next row.

Text Text Text Text Text Text Text Text Text Text Text Text Text Text Text Text Text Text Text
Text Text Text Text Text Text Text Text Text Text Text Text Text Text Text Text Text Text Text 
<sl-chip-group label="Label" help-text="This is optional help text">
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip disabled>Text</sl-chip>
</sl-chip-group>

<br/>

<sl-chip-group label="Label" help-text="This is optional help text" stacked>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip disabled>Text</sl-chip>
</sl-chip-group>

Chips Prefix and Suffix

We can use chip-group-prefix and chip-group-suffix to add a content, such as sl-button, before and after the chips respectively.

Prefix

Text Text Text Text Clear all 
<sl-chip-group label="Label" help-text="This is optional help text" stacked>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-button class="chip-group-prefix-clear-all-btn" variant="naked" slot="chip-group-prefix">Clear all</sl-button>
</sl-chip-group>

<script>
  const button = document.querySelector('sl-button.chip-group-prefix-clear-all-btn');
  button.addEventListener('click', (evt) => {
    const chipGroup = evt.target.closest('sl-chip-group');
    chipGroup.chips.forEach((c) => {
      c.active = false;
    });
  })
</script>

Suffix

Text Text Text Text Clear all 
<sl-chip-group label="Label" help-text="This is optional help text" stacked>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-button class="chip-group-suffix-clear-all-btn" variant="naked" slot="chip-group-suffix">Clear all</sl-button>
</sl-chip-group>

<script>
  const button = document.querySelector('sl-button.chip-group-suffix-clear-all-btn');
  button.addEventListener('click', (evt) => {
    const chipGroup = evt.target.closest('sl-chip-group');
    chipGroup.chips.forEach((c) => {
      c.active = false;
    });
  })
</script>

Label suffix

We can use slot label-suffix to add a suffix icon to the label. Label-suffix is a slot that sits next to the label. Icon buttons with tooltips are typically used to provide additional context.

Text Text Text Text Text
Text Text Text Text Text 
<sl-chip-group label="Label" help-text="This is optional help text">
  <sl-tooltip content="Label-suffix is a slot that sits next to the label. Icon buttons with tooltips are typically used to provide additional context." trigger="focus" slot="label-suffix">
    <sl-icon-button name="fal-circle-question"></sl-icon-button>
  </sl-tooltip>
  <sl-chip value="1">Text</sl-chip>
  <sl-chip value="2">Text</sl-chip>
  <sl-chip value="3">Text</sl-chip>
  <sl-chip value="4">Text</sl-chip>
  <sl-chip value="5" disabled>Text</sl-chip>
</sl-chip-group>

<br/>

<sl-chip-group label="Label" help-text="This is optional help text" stacked>
  <sl-tooltip content="Label-suffix is a slot that sits next to the label. Icon buttons with tooltips are typically used to provide additional context." trigger="focus" slot="label-suffix">
    <sl-icon-button name="fal-circle-question"></sl-icon-button>
  </sl-tooltip>
  <sl-chip value="1">Text</sl-chip>
  <sl-chip value="2">Text</sl-chip>
  <sl-chip value="3">Text</sl-chip>
  <sl-chip value="4">Text</sl-chip>
  <sl-chip value="5" disabled>Text</sl-chip>
</sl-chip-group>

Inline label sizes

By default, the inline label container has min-content width. To set the label width, use --form-control-label-width css custom variable on a parent element or the element itself.

Default

Text Text Text Text Text Text Text Text Text Text Text Text Text Text Text Text Text Text Text 
<sl-chip-group label="This is a label example that is longer" help-text="This is optional help text">
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip disabled>Text</sl-chip>
</sl-chip-group>

Fit content

Text Text Text Text Text Text Text Text Text Text Text Text Text Text Text Text Text Text Text 
<sl-chip-group class="auto-width" label="This is a label example that is longer" help-text="This is optional help text">
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip disabled>Text</sl-chip>
</sl-chip-group>


<style>
  .auto-width {
    --form-control-label-width: fit-content;
  }
</style>

Custom width

Text Text Text Text Text Text Text Text Text Text Text Text Text Text Text Text Text Text Text 
<sl-chip-group class="custom-width" label="This is a label example that is longer" help-text="This is optional help text">
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip>Text</sl-chip>
  <sl-chip disabled>Text</sl-chip>
</sl-chip-group>

<style>
  .custom-width {
    --form-control-label-width: 200px;
  }
</style>

[component-metadata:sl-chip-group]

Slots

Name Description
(default) The default slot.
label-suffix A label-suffix slot to add content after the label.
chip-group-prefix A slot to add content before the chips.
chip-group-suffix A slot to add content after the chips.

Learn more about using slots.

Properties

Name Description Reflects Type Default
label The chip group’s label. Required for proper accessibility. If you need to display HTML, use the label slot instead. string ''
helpText
help-text 		The chip groups’s help text. If you need to display HTML, use the help-text slot instead. string ''
name The name of the chip group, submitted as a name/value pair with form data. string 'option'
value The current value of the chip group, submitted as a name/value pair with form data. The value is a space-delimited string of selected chip values. For this reason, values must not contain spaces. string ''
defaultValue The default value of the form control. Primarily used for resetting the form control. string ''
form By default, form controls are associated with the nearest containing <form> element. This attribute allows you to place the form control outside of a form and associate it with the form that has this id. The form must be in the same document or shadow root for this to work. string ''
required Ensures a child chip is checked before allowing the containing form to submit. boolean false
size The chip group’s size. This size will be applied to all child chips. 'small' | 'medium' | 'large' 'medium'
stacked Whether the label should always be stacked boolean false
customInlineMsg
custom-inline-message 		The custom inline message string ''
showErrorMsgIcon
show-error-msg-icon 		Show an error icon next to the inline error message boolean false
showWarningMsgIcon
show-warning-msg-icon 		Show a warning icon next to the inline warning message boolean false
validity Gets the validity state object - -
validationMessage Gets the validation message - -
updateComplete A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.

Events

Name React Event Description Event Detail
sl-change Emitted when the chip group’s value changes. -

Learn more about events.

Methods

Name Description Arguments
checkValidity() Checks for validity but does not show a validation message. Returns true when valid and false when invalid. -
getForm() Gets the associated form, if one exists. -
reportValidity() Checks for validity and shows the browser’s validation message if the control is invalid. -
setCustomValidity() Sets a custom validation message. Pass an empty string to restore validity. message:

Learn more about methods.

Parts

Name Description
form-control The form control that wraps the label, input, and help text.
form-control-label The label’s wrapper.
form-control-input The input’s wrapper.
form-control-help-text The help text’s wrapper.

Learn more about customizing CSS parts.

Dependencies

This component automatically imports the following dependencies.

  • <sl-chip>
  • <sl-icon>