Use the label component to add metadata or indicate the status of items.

An image showing a group of labels with different styles, colors, leading icons and content.


Use labels to indicate the status of an item or to help oraganize and categorize them. E.g, using "New" or "Recommended". Labels aren't meant to be used as interactive elements. Instead use the Button component.


Use labels to categorize an item.


Don't use labels as an interactive or navigational element. Use a button or a link component.

Position the labels to clearly identify the object they’re informing.


Give labels enough space to be clearly identified. Use size or color to differentiate them if needed.


When used along with other items, don't place the label too close to them.


Use Label with with short, scannable text. If possible, use a single word to describe the status of an object. Use two or more words if you need to describe a complex state or category. For example, “Limited availability" or "Enterprise only".



Labels come in two sizes: medium, and large.


Use the medium size when paired with medium-sized headings or in components such as Card.

The Card component allows for a medium label to provide extra meta data to the content. In a group of stacked cards, the label helps to quickly scan certain items.

Medium labels are great for headings that introduce a section. They help categorize the main topic and provide a visual break.


Use the large size when paired with large headings, such as in the Hero component.

Use large labels with headings that introduce a page. Use it to introduce the main topic or application.


The label offers color options from the Primer Brand color palette. These color choices are carefully curated to ensure optimal contrast with the background or surrounding elements. Colors options doesn't follow a strict functional meaning. We recommend using the colors that best fit the context of your application. For example, blue and purple gradient for Copilot examples.

An image showing multiple label options with different colors.

Leading visual

You can add a leading icon to enhance the visual context. It is recommended you use an Octicon. Use an icon that reinforces the meaning of the label. For example, a StarIcon for a "Starred" label.

An image showing multiple label options with different leading visuals.

  • Button: To provide an action.
  • Link: To provide navigation.