Labels add metadata or indicate status of items and navigational elements. Three different types of labels are available: Labels for adding metadata, States for indicating status, and Counters for showing the count for a number of items.
The base label component styles the text, adds padding and rounded corners, and an inset box shadow. Labels come in various themes which apply colors and different border styles.
GitHub also programmatically generates and applies a background color for labels on items such as issues and pull requests. Users are able to select any background color and the text color will adjust to work with light and dark background colors.
Label style does not apply a background color. Here's an example using the
bg-blue utility to apply a blue background:
Note: Be sure to include a title attribute on labels, as it's helpful for people using screen-readers to differentiate a label from other text. For example, without the title attribute, the following case would read as "New select component design", rather than identifying
design as a label.
Labels come in a few different themes. Use a theme that helps communicate the content of the label, and ensure it's used consistently.
Label--gray to create a label with a light gray background and gray text. This label is neutral in color and can be used in contexts where all you need to communicate is metadata, or when you want a label to feel less prominent compared with labels with stronger colors.
Label--gray-darker to create a label with a dark-gray background color. This label is also neutral in color, however, since its background is darker, it can stand out more compared to
Label--orange to communicate "warning". The orange background color is very close to red, so avoid using next to labels with a red background color since most people will find it hard to tell the difference.
Label--outline to create a label with gray text, a gray border, and a transparent background. The outline reduces the contrast of this label in combination with filled labels. Use this in contexts where you need it to stand out less than other labels and communicate a neutral message.
Label--outline-green in combination with
Label--outline to communicate a positive message.
Issue labels are used for adding labels to issues and pull requests. They also come with emoji support.
If an issue label needs to be bigger, add the
Use state labels to inform users of an items status. States are large labels with bolded text. The default state has a gray background.
States come in a few variations that apply different colors. Use the state that best communicates the status or function.
Note: Similar to labels, you should include the title attribute on states to differentiate them from other content.
State--small for a state label with reduced padding a smaller font size. This is useful in denser areas of content.
Counter component to add a count to navigational elements and buttons. Counters come in 3 variations: the default
Counter with a light gray background,
Counter--gray with a dark-gray background and inverse white text, and
Counter--gray-light with a light-gray background and dark gray text. When a counter is empty, its visibility will be hidden.
Counter in navigation to indicate the number of items without the user having to click through or count the items, such as open issues in a GitHub repo. See more options in navigation.
Counters can also be used in
Box headers to indicate the number of items in a list. See more on the box component.
Diffstats show how many deletions or additions a diff has. It's typically a row of 5 blocks that get colored with green or red.
text-red utilities to add additional information about the size of the diff.