Form Pill Group

A Form Pill Group is an editable set of Pills that represent a collection of selectable or removable objects.

Version 8.0.1

const BasicFormPillGroup = () => {
  const pillState = useFormPillState();

  return (
    <form>
      <FormPillGroup {...pillState} aria-label="Products:">
        <FormPill {...pillState}>
         Voice
        </FormPill>
        <FormPill {...pillState}>
          <ProductVideoIcon decorative />
          Video
        </FormPill>
        <FormPill {...pillState}>
          <ProductVerifyIcon decorative />
          Verify
        </FormPill>
      </FormPillGroup>
    </form>
  );
};

render(
  <BasicFormPillGroup />
)

Guidelines

About Form Pill Group

A Form Pill Group is an editable set of Pills that represents a collection of selectable and/or removable objects. They are used almost exclusively in multi-select editing situations.

A Form Pill Group can be used on its own to represent selection across a number of fields, such as showing currently applied filters. It can also be paired directly with an input field, such as a Combobox, to represent multiple selections.

Accessibility

The only accessibility requirement is providing the Pill Group a descriptive label via the aria-label React prop.

The Form Pill Group is focusable, but only one pill is focusable at a time. This means the Pill Group is a single tab stop to a keyboard user. The dismiss button in a Form Pill is not a focusable element, but can be clickable.

Once a user focuses within the Form Pill Group, they can use these keyboard interactions:

Keyboard interaction	Action
Left and right arrow keys	Moving focus within the group
Enter key	Triggers the supplied action via onClick
Spacebar or enter keys	Selects a pill
Delete or backspace keys	Dismisses a pill

Form Pill vs. Display Pill

Form Pill Group creates a list from which a user may select items, whereas a Display Pill Group creates a list of static items.

Use the table below to get a better understanding of when to use Form Pill or Display Pill.

Functionality	Display Pill	Form Pill
Used to edit data in a form
Uses Listbox, Option semantic
Provides advanced keyboard navigation
Pills can be selected
Pills can perform an action
Pills can be dismissed
Used to view data
Uses List, List Item semantic
Pills can link to a page

Examples

Basic

This Form Pill example shows the basic static component that's exported by Paste. A Form Pill can have an optional Avatar or Icon placed before the text.

Interaction states on Form Pills need to be managed separately as shown in the examples after this one by using the useFormPillState hook. The returned state should be spread onto each component. This will provide you with some internal state management and keyboard navigation.

A Form Pill can have an optional Avatar or Icon placed before the text.

const BasicFormPillGroup = () => {
  const pillState = useFormPillState();

  return (
    <form>
      <FormPillGroup {...pillState} aria-label="Products:">
        <FormPill {...pillState}>
         Voice
        </FormPill>
        <FormPill {...pillState}>
          <ProductVideoIcon decorative />
          Video
        </FormPill>
        <FormPill {...pillState}>
          <ProductVerifyIcon decorative />
          Verify
        </FormPill>
      </FormPillGroup>
    </form>
  );
};

render(
  <BasicFormPillGroup />
)

Selectable

Use a Selectable Form Pill to show an option that a user can select or deselect.

To make pills inside the Pill Group selectable, you can manage the selection state yourself and combine it with the state returned from the useFormPillState hook. To do so, track which pill is selected in a separate store of state. When rendering the Form Pill Group, cross reference the rendered pills with the selection state, and conditionally set selected on each FormPill that requires it.

The onSelect event handler will fire whenever the pill is clicked, or the spacebar or enter key is pressed. Use this to respond to your users' selection interactions.

const SelectableFormPillGroup = () => {
  const [pills] = React.useState(['SMS', 'MMS', 'Fax', 'Voice', 'Messaging', 'Chat']);
  const [selectedSet, updateSelectedSet] = React.useState(new Set(['MMS', 'Voice', 'Chat']));
  const pillState = useFormPillState();

  const iconMap = {
    ['Fax']: <FaxCapableIcon decorative/>,
    ['Voice']: <ProductVoiceIcon decorative/>,
    ['Messaging']: <ProductMessagingIcon decorative/>,
    ['Chat']: <ProductChatIcon decorative/>,
  }

  return (
    <form>
      <FormPillGroup {...pillState} aria-label="Products:">
        {pills.map((pill) => (
          <FormPill
            key={pill}
            {...pillState}
            selected={selectedSet.has(pill)}
            onSelect={() => {
              const newSelectedSet = new Set(selectedSet);
              if (newSelectedSet.has(pill)) {
                newSelectedSet.delete(pill);
              } else {
                newSelectedSet.add(pill);
              }
              updateSelectedSet(newSelectedSet);
            }}
          >
            {iconMap[pill]}
            {pill}
          </FormPill>
        ))}
      </FormPillGroup>
    </form>
  );
};

render(
  <SelectableFormPillGroup />
)

Dismissible

Use a Dismissible Form Pill to show an option that a user can remove from the group. Once the pill is dismissed, it can’t be rerendered.

Form Pills are given a close button when provided an onDismiss event handler. Because the Form Pill Group is largely presentational, provide dismissible functionality by managing the state of the rendered pills. By responding to user interactions and hooking into the onDismiss event handler, the rendered state of the Form Pill Group can be updated and pills can be selectively removed from the collection.

The onDismiss event handler will fire when a user clicks on the close button, or presses their backspace or delete key when focused on a pill.

const DismissableFormPillGroup = () => {
  const [pills, setPills] = React.useState(['Frontline', 'Phone Numbers', 'Authy']);
  const pillState = useFormPillState();

  const iconMap = {
    ['Phone Numbers']: <ProductPhoneNumbersIcon decorative/>,
  }

  return (
    <form>
      <FormPillGroup {...pillState} aria-label="Products:">
        {pills.map((pill, index) => (
          <FormPill
            key={pill}
            {...pillState}
            onDismiss={() => {
              setPills(pills.filter((_, i) => i !== index));
            }}
          >
            {iconMap[pill]}
            {pill}
          </FormPill>
        ))}
      </FormPillGroup>
    </form>
  );
};

render(
  <DismissableFormPillGroup />
)

Selectable and dismissible

Use a Selectable and Dismissible Form Pill to show an option that a user can select, deselect, or dismiss. Once the pill is dismissed, it can’t be re-rendered.

The onSelect event handler will fire when a user clicks on the pill. The onDismiss event handler will fire when a user clicks on the close button.

The onSelect event handler will fire when a user presses the spacebar or enter keys. The onDismiss event handler will fire when a user presses the delete or backspace keys.

const SelectableAndDismissableFormPillGroup = () => {
  const [pills, setPills] = React.useState(['Proxy', 'Interconnect', 'Trust Hub']);
  const [selectedSet, updateSelectedSet] = React.useState(new Set(['Interconnect']));
  const pillState = useFormPillState();

  const iconMap = {
    ['Interconnect']: <ProductInterconnectIcon decorative/>,
  }

  return (
    <form>
      <FormPillGroup {...pillState} aria-label="Products:">
        {pills.map((pill, index) => (
          <FormPill
            key={pill}
            {...pillState}
            onDismiss={() => {
              setPills(pills.filter((_, i) => i !== index));
              if (selectedSet.has(pill)) {
                const newSelectedSet = new Set(selectedSet);
                newSelectedSet.delete(pill);
                updateSelectedSet(newSelectedSet);
              }
            }}
            selected={selectedSet.has(pill)}
            onSelect={() => {
              const newSelectedSet = new Set(selectedSet);
              if (newSelectedSet.has(pill)) {
                newSelectedSet.delete(pill);
              } else {
                newSelectedSet.add(pill);
              }
              updateSelectedSet(newSelectedSet);
            }}
          >
            {iconMap[pill]}
            {pill}
          </FormPill>
        ))}
      </FormPillGroup>
    </form>
  );
};

render(
  <SelectableAndDismissableFormPillGroup />
)

Internationalization

To internationalize the form pill group, simply pass different text as children to the pills. The only exceptions to this are the visually hidden text that explains how to dismiss and select pills and the error label for the error variant. To change these, pass the i18nKeyboardControls and i18nErrorLabel props.

const I18nFormPillGroup = () => {
  const pillState = useFormPillState();

  return (
    <form>
      <FormPillGroup
        {...pillState}
        aria-label="Votre sports favoris:"
        i18nKeyboardControls="Appuyez sur Supprimer ou Retour arrière pour supprimer. Appuyez sur Entrée pour basculer la sélection."
      >
        <FormPill {...pillState} variant="error" i18nErrorLabel="(Erreur)">
          Le tennis
        </FormPill>
        <FormPill {...pillState}>
          Le football américain
        </FormPill>
        <FormPill {...pillState} variant="error" i18nErrorLabel="(Erreur)">
          Le ski
        </FormPill>
        <FormPill {...pillState}>Le football</FormPill>
      </FormPillGroup>
    </form>
  );
};

render(
  <I18nFormPillGroup />
)

States

Default or unselected

The default state of a Form Pill indicates that the control is static or not selected.

const BasicFormPillGroup = () => {
  const pillState = useFormPillState();

  return (
    <form>
      <FormPillGroup {...pillState} aria-label="Products:">
        <FormPill {...pillState}>
         Voice
        </FormPill>
        <FormPill {...pillState}>
          <ProductVideoIcon decorative />
          Video
        </FormPill>
        <FormPill {...pillState}>
          <ProductVerifyIcon decorative />
          Verify
        </FormPill>
      </FormPillGroup>
    </form>
  );
};

render(
  <BasicFormPillGroup />
)

Selected

A Form Pill can be placed into a selected state by setting the selected property.

const SelectedStateExample = () => {
  const pillState = useFormPillState();

  return (
    <form>
      <FormPillGroup {...pillState} aria-label="Products:">
        <FormPill {...pillState} selected>
         Voice
        </FormPill>
        <FormPill {...pillState} selected>
          <ProductVideoIcon decorative />
          Video
        </FormPill>
        <FormPill {...pillState} selected>
          <ProductVerifyIcon decorative />
          Verify
        </FormPill>
      </FormPillGroup>
    </form>
  );
};

render(
  <SelectedStateExample />
)

Error

Use an Error Form Pill to highlight an object that the user must be made aware of because it’s considered to be in a bad or broken state and should be addressed. An error icon will display as a prefix to the rest of the children in the pill.

When used in a form field, display an error message below the form field to provide guidance on how to fix the error. For additional guidance on how to compose error messages, refer to the error state pattern.

const ErrorStateExample = () => {
  const pillState = useFormPillState();

  return (
    <form>
      <FormPillGroup {...pillState} aria-label="Products:">
        <FormPill {...pillState} variant="error">
         Voice
        </FormPill>
        <FormPill {...pillState} variant="error" selected>
          <ProductVideoIcon decorative />
          Video
        </FormPill>
        <FormPill {...pillState} variant="error">
          <ProductVerifyIcon decorative />
          Verify
        </FormPill>
        <FormPill {...pillState} variant="error" selected>
         Usage
        </FormPill>
      </FormPillGroup>
    </form>
  );
};

render(
  <ErrorStateExample />
)

Disabled

Use a disabled Form Pill to indicate that a particular option cannot be interacted with or can be safely ignored.

const DisabledStateExample = () => {
  const pillState = useFormPillState();

  return (
    <form>
      <FormPillGroup {...pillState} aria-label="Products:">
        <FormPill {...pillState} disabled>
         Voice
        </FormPill>
        <FormPill {...pillState} disabled>
          <ProductVideoIcon decorative />
          Video
        </FormPill>
        <FormPill {...pillState} disabled>
          <ProductVerifyIcon decorative />
          Verify
        </FormPill>
        <FormPill {...pillState} disabled>
         Usage
        </FormPill>
      </FormPillGroup>
    </form>
  );
};

render(
  <DisabledStateExample />
)

Composition notes

Truncating text

Pill text should never wrap to the next line. If the text length is longer than the max width of the pill group’s container, consider moving the Pill to a new row or use Truncate to truncate the Form Pill text.

const TruncateFormPillGroup = () => {
  const pillState = useFormPillState();

  return (
    <form>
      <FormPillGroup {...pillState} aria-label="Products:">
        <FormPill {...pillState}>
          <ProductInternetOfThingsIcon decorative />
          <Box maxWidth="size10">
            <Truncate title="Internet of Things">Internet of Things</Truncate>
          </Box>
        </FormPill>
        <FormPill {...pillState}>
          <ProductMarketingCampaignsIcon decorative />
          <Box maxWidth="size10">
            <Truncate title="Marketing Campaigns">Marketing Campaigns</Truncate>
          </Box>
        </FormPill>
        <FormPill {...pillState}>
          <ProductCodeExchangePartnerIcon decorative />
          <Box maxWidth="size10">
            <Truncate title="CodeExchange Partner">CodeExchange Partner</Truncate>
          </Box>
        </FormPill>
        <FormPill {...pillState}>
          <ProductEngagementIntelligencePlatformIcon decorative />
          <Box maxWidth="size10">
            <Truncate title="Engagement Intelligence Platform">Engagement Intelligence Platform</Truncate>
          </Box>
        </FormPill>
      </FormPillGroup>
    </form>
  );
};

render(
  <TruncateFormPillGroup />
)

Adding an avatar

A Form Pill can have an optional Avatar. Considering the size of a Form Pill, it is recommended to use either an image or icon within an Avatar, and to avoid using initials as some initials may get cut off if the characters are particularly wide.

We recommend placing the Avatar ahead of the pill text. Use no more than one before or after the text.

const AvatarFormPillGroup = () => {
  const pillState = useFormPillState();

  return (
    <form>
      <FormPillGroup {...pillState} aria-label="People:">
        <FormPill {...pillState}>
          <Avatar size='sizeIcon30' name='Customer' src="/images/avatars/avatar4.png" />
          Customer
        </FormPill>
        <FormPill {...pillState}>
          <Avatar size='sizeIcon30' name='Agent' icon={AgentIcon} />
          Agent
        </FormPill>
      </FormPillGroup>
    </form>
  );
};

render(
  <AvatarFormPillGroup />
)

Adding an icon

A Form Pill can have an optional Icon. We recommend placing the Icon ahead of the pill text. Use no more than one before or after the text.

const IconFormPillGroup = () => {
  const pillState = useFormPillState();

  return (
    <form>
      <FormPillGroup {...pillState} aria-label="Products:">
        <FormPill {...pillState}>
          <ProductMessagingIcon decorative />
          Messaging
        </FormPill>
        <FormPill {...pillState}>
          <ProductBillingIcon decorative />
          Billing
        </FormPill>
        <FormPill {...pillState}>
          <ProductLookupIcon decorative />
          Lookup
        </FormPill>
        <FormPill {...pillState}>
          <ProductConversationsIcon decorative />
          Conversations
        </FormPill>
      </FormPillGroup>
    </form>
  );
};

render(
  <IconFormPillGroup />
)

When to use a Form Pill Group

Use a Form Pill Group when you’re editing a collection of data within a form. It can be used to represent selection across multiple fields such as filtering, or from a single field like a Combobox.

Do

Use Form Pills inside of a form or when editing a collection of data.

Don't

Don’t use Form Pills in non-editable pages to represent a collection of similar objects, outside of a form, or outside of editing scenarios. Use a Display Pill Group instead.

Do

Only pass FormPill as a direct descendent of a FormPillGroup.

Don't

Don't pass FormPillGroup any other component type, and do not wrap FormPill in any other component of DOM element.

Form Pill Group

Guidelines

About Form Pill Group

Accessibility

Keyboard navigation

Form Pill vs. Display Pill

Examples

Basic

Selectable

Dismissible

Selectable and dismissible

Mouse navigation

Keyboard navigation

Internationalization

States

Default or unselected

Selected

Error

Disabled

Composition notes

Truncating text

Adding an avatar

Adding an icon

When to use a Form Pill Group

Do

Don't

Do

Don't