Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Original file line number Diff line number Diff line change
Expand Up @@ -2,17 +2,21 @@
id: Label
section: components
---

import '../components.css';

## Labels

### Elements
You can customize labels by adjusting their visual styling or adding functionality to let users click, edit, or remove labels.

![Different label variants for both nonstatus and status labels.](./img/label-elements.png)

<div class="ws-docs-content-img">
![Elements of both status and non-status labels.](./img/label-elements.svg)
</div>

1. **Status label:** Combines color and an icon to communicate a status, like danger, warning, or success.
1. **Filled label:** Can be used for additional emphasis.
1. **Unfilled label:** Can be used as a less prominent label style.
1. **Outlined label:** Can be used as a less prominent label style.
1. **Compact label:** Takes up less space than the default label.
1. **Label with icon:** Can utilize a recognizable icon to make the label more clear and identifiable.
1. **Clickable label:** Is identified by the inclusion of a hover state (as shown in the example image).
Expand All @@ -30,7 +34,9 @@ Labels are useful in a few scenarios:

There are 2 label sizes:

![Default and compact-sized labels.](./img/label-sizes.png)
<div class="ws-docs-content-img">
![Example of default and compact labels.](./img/label-sizes.svg)
</div>

1. **Default labels:** Use by default when needing a label.
2. **Compact labels:** Use when confronted by space limitations and a smaller label is required (for example, in a table).
Expand All @@ -39,17 +45,23 @@ Labels can be used almost anywhere in a UI. They are commonly used in tables, ca

#### Labels in tables

![Labels within a table.](./img/table-with-labels.png)
<div class="ws-docs-content-img">
![Example of labels within a table.](./img/table-with-labels.svg)
</div>

#### Labels in card views

![Labels on cards in a card view.](./img/card-view-labels.png)
<div class="ws-docs-content-img">
![Example of labels on cards in a card view.](./img/card-view-labels.svg)
</div>

#### Filter labels

Labels are typically used in filter and selection use cases to indicate what selections a user has made. They utilize [label groups](#label-groups) to organize selections by category for added clarity. When there are multiple filter labels within a group, any data that matches one or more of the labels will be filtered. It is not required for all filter labels to be applied in order to match a filtered item.

![Labels as filters in a toolbar.](./img/label-filters.png)
<div class="ws-docs-content-img">
![Example of labels as filters in a toolbar.](./img/label-filters.svg)
</div>

#### Color considerations

Expand All @@ -63,13 +75,17 @@ The colors you should use differs for status and nonstatus labels:

Status colors can be used to indicate danger, warning, success, info, or custom statuses.

![Filled status labels in light and dark color themes.](./img/status-labels.png)
<div class="ws-docs-content-img">
![Examples of filled status labels in light and dark color themes.](./img/status-labels.svg)
</div>

##### Nonstatus labels

We offer a nonstatus color palette, which you can use to color code labels that don't correspond to any status level, including red, orange, orange red, gold, green, cyan, blue, purple, and gray.

![Filled nonstatus labels in light and dark color themes.](./img/nonstatus-labels.png)
<div class="ws-docs-content-img">
![Examples of filled non-status labels in light and dark color themes.](./img/nonstatus-labels.svg)
</div>

**Note:** We recommend you avoid using red, unless you're indicating danger or an error state.

Expand All @@ -88,36 +104,47 @@ Both status and nonstatus labels can be filled or unfilled.

##### Filled

![All color options for filled labels for light and dark themes.](./img/filled-labels.png)
<div class="ws-docs-content-img">
![Examples of all the color options for filled labels in light and dark themes.](./img/Filled-labels.svg)
</div>

##### Unfilled

![All color options for unfilled label styles for light and dark themes.](./img/unfilled-labels.png)
<div class="ws-docs-content-img">
![Examples of all color options for unfilled labels in light and dark themes.](./img/Unfilled-labels.svg)
</div>

#### When to use labels with icons

While status labels will automatically contain an appropriate icon, you can also add an icon to nonstatus labels, when additional visual information would be helpful.

![Icons within labels in a card.](./img/card-labels.png)
<div class="ws-docs-content-img">
![Example of labels with icons in a card.](./img/card-labels.svg)
</div>

Icons can also help distinguish labels of the same color.

#### When to use editable labels
Use editable labels when you want to allow users to organize and select resources manually. Adding editable labels enables the user to query for objects that have similar, dissimilar, or overlapping labels.

![Before and after example of editing a label.](./img/editable-labels.png)
<div class="ws-docs-content-img">
![Example showing the before and after of editing a label.](./img/editable-labels.svg)
</div>

#### When to use dismissible labels

Use a dismissible label for labels that can be easily removed. Editable labels are often dismissible as well.

![Before and after example of dismissing a label.](./img/dismissible-labels.png)
<div class="ws-docs-content-img">
![Example showing the before and after of dismissing a label.](./img/dismissible-labels.svg)
</div>

#### When to use clickable labels
Use a clickable label for labels that trigger actions or link to new pages.

As shown in the following image, a common use case for clickable labels is when a user may want to filter by a specific label.
Use a clickable label for labels that trigger actions or link to new pages. Clickable labels include a hover state as shown in the following image.

![Example of clicking a label to filter on that label.](./img/clickable-labels.png)
<div class="ws-docs-content-img">
![Example of a clickable label.](./img/clickable-labels.svg)
</div>

## Label groups

Expand All @@ -126,7 +153,9 @@ Label groups are used to display multiple labels at once.
### Elements
Label groups have a number of components to them.

![Different elements of a label group.](./img/label-group-elements.png)
<div class="ws-docs-content-img">
![Elements of a label group.](./img/label-group-elements.svg)
</div>

1. **Label:** Indicates the labels applied.
1. **Group label (optional):** Indicates the group category or name.
Expand All @@ -142,16 +171,23 @@ Label groups should be used when there are multiple labels assigned to a compone

In a table, basic label groups can be used to display all labels associated with a data source.

![Label groups within a table.](./img/table-with-label-group.png)
<div class="ws-docs-content-img">
![Example of label groups within a table.](./img/table-with-label-group.svg)
</div>

#### Label groups in a table popover

When there are many labels assigned to a table, you can use a popover as a container.

![Vertical label group within a popover.](./img/label-group-popover.png)
<div class="ws-docs-content-img">
![Example of a vertical label group within a popover.](./img/label-group-popover.svg)
</div>

#### Label groups in a description list

![Label group within a description list field.](./img/description-list-labels.png)
<div class="ws-docs-content-img">
![Example of a label group within a description list field.](./img/description-list-labels.svg)
</div>

### Variations

Expand All @@ -161,28 +197,36 @@ When there are many labels assigned to a table, you can use a popover as a conta

This pattern can be followed to let users add a new label or edit an existing label within a group.

![Table-based label group with option to add a new label.](./img/adding-label.png)
<div class="ws-docs-content-img">
![Example of a label group within a table with the option to add a new label.](./img/adding-label.svg)
</div>

When a user selects the **Add label** button, a new label is added to the beginning of the group. Once the new label is added, they can overwrite the default value by double clicking the label.

![Table-based label group example, after a new label is added.](./img/added-label.png)
<div class="ws-docs-content-img">
![Example of a label group within a table after a new label is added.](./img/added-label.svg)
</div>

##### Adding a new label to a group from a list of preselected labels

You can provide users with a fixed set of label options to add to a group.

When a user selects the **Add label** button, display a menu of available label options. They can select a new label from the values in the menu.

![Dropdown menu of label options when trying to add a new label to a group.](./img/adding-label-options.png)
<div class="ws-docs-content-img">
![Example of a dropdown menu with options when trying to add a new label to a group.](./img/adding-label-options.svg)
</div>

The new label is added with the selected value and can not be edited.
##### Adding a new custom label to a label group
##### Adding a new custom label to a label groupgit

You can allow users to customize the labels they add to a group.

When a user selects the **Add label** button, it opens up a modal, where they can select the attributes for their new label, including the label type, text, color, icon, and the ability to dismiss or edit. Customize these options to fit your needs.

![Modal with selectable options used to create a new label.](./img/adding-label-modal.png)
<div class="ws-docs-content-img">
![Example of a modal used to create a new label.](./img/adding-label-modal.svg)
</div>

Once the new label is created, it cannot be edited. Users will need to add a new label if they want to make changes.
## Accessibility
Expand Down