Pill

A lightning-pill component represents an item, such as an account name or case number. By default, pills are rendered with a remove button. They’re useful for displaying read-only text that can be added and removed on demand, for example, a list of email addresses or a list of keywords.

This example creates a basic pill with a link.

URLs without a protocol use the host domain's protocol. For example, www.example.com is prefixed with https:// if the host domain's protocol is https://.

A pill can contain an icon or avatar to represent the type of object. Nest a lightning-icon or lightning-avatar component inside the lightning-pill component.

Insert an icon on the pill using lightning-icon. For more information, see lightning-icon.

Insert an avatar on the pill using lightning-avatar. For more information, see lightning-avatar.

A pill has three clickable elements.

• The optional icon or avatar
• The text label
• The remove button

All three elements trigger the onclick handler when clicked. If you provide an href value, clicking the text label triggers the onclick handler and then takes you to the provided path.

Clicking the remove button on the pill fires the remove event and then the click event. Use the optional onremove and onclick handlers to remove the pill and perform an action. You must hide or remove the pill on your own using the onremove handler, as shown in the example below. If you don't specify a pill removal behavior, clicking the remove button doesn't have a visible effect.

When an href value is present, clicking the text label navigates to a link, but clicking the icon or avatar doesn’t. To prevent your browser from navigating to a link when you click a pill's label, call event.preventDefault() in the onclick handler.

When an href value is present, the default variant is link. If no href is present, the default variant is plain.

To disable a pill's link, set variant="plain", which removes the anchor element. The plain variant renders the pill without a link and ignores the href attribute.

This example hides a pill when the remove button is clicked.

To prevent navigating to the link when the remove button is clicked, call event.preventDefault() in the onremove handler. The click event is still fired when you click the text label. However, calling event.preventDefault() in the onremove handler prevents the click event from firing when you click the remove button.

Display a pill in an error state when the containing text doesn't match a pre-defined collection of items, such as when an email address is invalid or a case number doesn't exist.

Use the has-error attribute to denote an error on a pill. This attribute inserts an error icon next to the label and changes the label text to red. Providing an icon or avatar in this context has no effect on the pill; the error icon is still displayed.

lightning-pill implements the pills blueprint in the Salesforce Lightning Design System (SLDS).

To apply additional styling, use the SLDS utility classes with the class attribute.

This example adds padding on the left of the second pill using an SLDS class.

Component styling hooks use the --slds-c-* prefix and change styling for specific elements or properties of a component. Component-specific styling isn’t recommended, because it’s unsupported for SLDS 2, but existing customizations still work with the original SLDS. If you use component styling hooks, limit the components to SLDS themes until SLDS 2 and the Salesforce Cosmos theme become generally available. See Pills: Styling Hooks Overview for documentation on component-specific hooks for this component.

For more information, see Style Components Using Lightning Design System Styling Hooks in the Lightning Web Components Developer Guide.

Icons are not available in Lightning Out, but they are available in Lightning Components for Visualforce and other experiences.

To create more than one pill, use the lightning-pill-container component, which gives you access to the pill array via the itemremove event.

Specifying a target to change where the link should open is not supported. The link opens on the same tab or window. To create a URL that navigates to another page in Salesforce, use lightning-navigation.

This component has usage differences from its Aura counterpart. See Base Components: Aura Vs Lightning Web Components in the Lightning Web Components Developer Guide.

When using lightning-avatar, use the alternative-text attribute to describe the avatar, such as a user's initials or name. This description provides the value for the alt attribute in the img HTML tag.

When using lightning-icon, use the alternative-text attribute to describe the icon. For example, specify "Account" instead of "Pill icon". This description is used as assistive text on the pill.

Press the Tab key to move focus to a pill with a link, and tab again to move focus to the remove button. To remove a pill, press the Enter key or space bar when the focus is on the remove button. You can define your own behavior to remove the pill from view, such as using the onremove handler shown in Interacting with Pills. To navigate to the target of a link on a pill, press the Enter key when the focus is on the pill.

If a pill doesn't have a link, the only focusable item is the remove button.

remove

The first event fired when you click the remove button.

The remove event returns the following parameter.

The event properties are as follows.