Badge

Import

import { Badge, DiffStat } from '@envsemble/envui';

Usage

A Badge's label is its children, a state, a name or a category in a word or two, with an optional decorative icon before it. It stays on one line and ends with an ellipsis where it is wider than its container.

ProjectStatus.tsx

import { Badge, Column, Row, Text } from '@envsemble/envui';

export default function ProjectStatus() {
  return (
    <Column gap={1}>
      <Row align="center" gap={2}>
        <Text render={<h3 />} variant="title">
          Northwind launch
        </Text>
        <Badge tone="warning">Blocked</Badge>
      </Row>
      <Text emphasis="muted">Waiting on two decisions from the design review.</Text>
    </Column>
  );
}

Variants and tones

variant is one of:

soft, the default: it tints the background without an edge. Primary, accent, success, warning and danger take the tone's stronger tint, with a semibold label.
solid: it fills the background with the tone.
outline: it draws a border.

tone is neutral, the default, primary, the blue of what is current, accent, the purple that stands out, success, warning, danger or done. Done is the slate of completed work: a quiet blue-gray in a fainter tint than neutral, so finished things recede, apart from the success green, the accent purple and the primary blue. A done badge leads with a check mark, which tells it from a neutral one by more than its hue; another icon replaces it, and icon={null} leaves it out.

<Badge tone="success">Ready</Badge>
<Badge tone="danger" variant="solid">Overdue</Badge>
<Badge variant="outline">Design team</Badge>

Counts

count takes a number, such as 12, or short text, such as 99+, in place of a label: a compact round pill in tabular figures. Pass 99+ yourself beyond two digits. Its aria-label, such as 12 unread, is read in place of the number. Counts take the same tones and variants; tone="accent" variant="solid" draws attention to one.

<Button>
  Comments <Badge count={4} />
</Button>
<Button>
  Review requests <Badge count={2} tone="primary" variant="solid" />
</Button>

DiffStat

DiffStat shows additions as +12 in the success tone and deletions as −3 in the danger tone, in the locale's digits, and leaves out a side that is 0, so a change that only adds reads +40. It is named once for assistive technology, such as 12 added lines and 3 removed lines, or from its own formatLabel.

<DiffStat additions={12} deletions={3} />

A NavigationDrawer destination's count shows the count at its end and adds it to the destination's name, such as Inbox, 12 new.

const destinations: Destination[] = [
  { label: 'Inbox', icon: <IconInbox />, href: '/inbox', count: 12, current: true },
  { label: 'Later', icon: <IconSchedule />, href: '/later', count: 1200 },
];

<NavigationDrawer aria-label="Workspace" destinations={destinations} />;

Composition

The parts are the pill, env-badge, its icon, env-badge > env-icon, and its label, env-badge-label. A count is env-badge[data-count], with env-badge-count-label for its aria-label; DiffStat has env-diff-stat-additions and env-diff-stat-deletions.

Accessibility

You provide

An aria-label on a count whose number doesn't explain itself, such as 12 unread.
A status region where a change of count must be announced.

envUI provides

The label as text, read in place; the icon hidden.
A count's aria-label read instead of its number.
A DiffStat named once, such as 12 added lines and 3 removed lines, or from formatLabel.

Props

A small pill label for a state, such as In progress, Blocked or Archived, or for neutral metadata, such as a plan or a count of seats; with count, a compact count, such as 12 unread.

Prop	Type	Description
`icon`	`ReactNode`	A decorative icon before the label, such as a check mark; hidden from assistive technology. A done badge has a check mark unless it is given another icon, or `null` for none.
`children`	`ReactNode`	The label: a state, a name or a category in a word or two. It stays on one line and ends with an ellipsis where the badge is wider than its container.
`count`	`numberstring`	A count, such as 12, or short text such as 99+, in place of a label: a compact round pill, in tabular figures, as beside a navigation label, in a tab or on a button.
`tone`Default `'neutral'`	`'neutral''primary''accent''success''warning''danger''done'`	Meaning of the state: primary is the blue of what is current, accent the purple that stands out, done the quiet slate of completed work, which leads with a check mark. Neutral by default. A count in the primary tone, solid, draws attention, such as unread messages that need an answer.
`variant`Default `'soft'`	`'soft''solid''outline'`	soft tints the background, solid fills it with the tone, outline draws a border.
`aria-label`	`string`	What the count means, such as 12 unread, which assistive technology reads in place of the number; the number alone otherwise.

Also accepts the native props of <span>, such as ref, className and aria-* attributes.

DiffStat

The size of a change as one compact pill, such as +12 −3: additions in the success tone and deletions in the danger tone, on a counter badge's quiet fill.

Prop	Type	Description
`additions`required	`number`	Lines or items added, shown as +12 in the success tone, in the locale's digits; left out where it is 0 and deletions aren't.
`deletions`required	`number`	Lines or items removed, shown as −3 in the danger tone, in the locale's digits; left out where it is 0 and additions aren't.
`formatLabel`Default `'{additions} added lines and {deletions} removed lines'`	`(additions: number, deletions: number) => string`	Full meaning for assistive technology. It overrides EnvUIProvider's `messages.diffStat.label`.

Also accepts the native props of <span>, such as ref, className and aria-* attributes.

Part names

Each part's class and state attributes are public and versioned, for an application's CSS to style.

`Badge`

env-badge: The badge: a small pill label, or with data-count a compact count.
env-badge-count-label: What a count means, such as 12 unread, for assistive technology; visually hidden.
env-badge-label: The badge's text, or its count.
data-count: Present
data-tone: accent · danger · done · neutral · primary · success · warning
data-variant: outline · soft · solid

`DiffStat`

env-diff-stat: The count of added and removed lines.
env-diff-stat-additions: The added lines.
env-diff-stat-deletions: The removed lines.
env-diff-stat-label: The label for assistive technology.

Color properties

Each sets a color of one instance, through style or CSS; its hover, focus and press follow it. They are public and versioned.

--env-badge-container: The fill, in place of the tone and variant.
--env-badge-content: The label, count or icon.
--env-badge-outline: An edge in this color.

Strings

EnvUIProvider's messages overrides each, and a component's own label prop wins over it.

messages.diffStat.label: ({ additions, deletions, additionsText, deletionsText }) => string Names the counts, such as 12 added lines and 3 removed lines; `additionsText` and `deletionsText` are the counts in the locale's digits.

Changelog

1.0.0: A soft badge in the accent, success, warning or danger tone takes the tone's stronger tint, and its label is semibold; at high contrast it keeps the softer tint.

InfoChip is Badge, a pill, and its page joins this one. The subtle variant is soft. Counter is a Badge with count, .env-badge[data-count] with env-badge-count-label, and DiffCount is DiffStat, with its props type and the env-diff-stat-* classes; the page is badge. DiffStat writes its numbers and its name in the locale, and its name comes from messages.diffStat.label. A control sets the badges inside it through the --env-badge-*, --env-badge-count-* and --env-diff-stat-* hooks.
1.0.0-prerelease.6: A done badge leads with a check mark, and a soft one takes a fainter tint than neutral. On a selected Table row or List item, a soft badge lays its tint over the raised surface, so it stays apart from the selection's blue. DiffStat leaves out a side that is 0, such as +40 for a change that only adds.

The done tone is a quiet slate blue-gray, in place of a cyan that sat too close to the success green at table size: completed things recede.
1.0.0-prerelease.5: A little roomier: 3 px above and below its label and 10 px at the sides, edge included.

Import

Usage

Variants and tones

Counts

DiffStat

In navigation

Composition

Accessibility

You provide

envUI provides

Props

Badge

DiffStat

Part names

Badge

DiffStat

Color properties

Strings

Changelog

`Badge`

`DiffStat`