Badge

A small mark in the corner of something else: unread mail on an inbox icon, a status dot on an avatar, a count on a tab.

import { Badge, Button } from 'neba';

<Badge content={4} label="4 unread notifications">
  <Button startIcon={<BellIcon />} />
</Badge>

<Badge dot color="success" overlap="circle">
  <Avatar />
</Badge>;

Props

Prop	Type	Default	Description
variantshared	'solid' | 'outline' | 'text'	'solid'	Weight of the surface: filled, hairline, or none
sizeshared	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	The size of the mark, on a ladder of its own: a badge hangs off a corner, so it lines up with nothing
colorshared	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	Semantic colour role. Arbitrary colour values are not accepted
densityshared	'default' | 'compact'	'default'	The room around the digits, and nothing else
elevationshared	0 | 1 | 2 | 3	0	Drop shadow depth. 0 means no shadow at all
content	ReactNode	—	What the badge says — usually a count. Omit it and the badge draws a dot
max	number	99	Caps a numeric content and adds a plus. Text is never truncated
dot	boolean	false	Draws a dot even with content, keeping the count for screen readers only
showZero	boolean	false	Shows a count of zero. Off by default — zero unread messages is not news
invisible	boolean	false	Hides the marker without giving up its box, so nothing moves when it returns
placementshared	'top-start' | 'top-end' | 'bottom-start' | 'bottom-end'	'top-end'	Which corner it sits on. start/end, so the corner flips with the writing direction
overlap	'square' | 'circle'	'square'	The shape underneath, which decides how far the mark tucks in — a circle's corner is further out than a square's
label	string	—	What a screen reader hears instead of the raw count — "3" beside a bell means nothing
children	ReactNode	—	What the badge is pinned to. Without it, the badge is a standalone marker that lays out inline

Examples

Variants and colours

import { Badge, Button } from 'neba';

const COLORS = ['primary', 'secondary', 'success', 'warning', 'danger', 'info'] as const;

export default function BadgeVariants() {
  return (
    <div className="flex flex-col gap-4">
      {(['solid', 'outline', 'text'] as const).map((variant) => (
        <div key={variant} className="flex flex-wrap items-center gap-5">
          {COLORS.map((color) => (
            <Badge key={color} variant={variant} color={color} content={8}>
              <Button variant="outline" color="secondary" size="sm">
                {color}
              </Button>
            </Badge>
          ))}
        </div>
      ))}
    </div>
  );
}

What it says

A number past max becomes 99+ rather than growing. Text is never truncated — a badge cannot know how to shorten a word.

A content of 0 draws nothing by default. Zero unread messages is not news, and a badge that never goes away stops meaning anything. When there is nothing to count but something to report, that is what dot is.

import { Badge, Button } from 'neba';

export default function BadgeContent() {
  return (
    <div className="flex flex-wrap items-center gap-6">
      <Badge content={7}>
        <Button variant="outline" color="secondary">
          Seven
        </Button>
      </Badge>

      {/* Past `max`, and the badge says so rather than growing. */}
      <Badge content={1204}>
        <Button variant="outline" color="secondary">
          Capped
        </Button>
      </Badge>

      <Badge content={1204} max={999}>
        <Button variant="outline" color="secondary">
          Higher cap
        </Button>
      </Badge>

      {/* A count of nothing is not news, so it does not show up at all. */}
      <Badge content={0}>
        <Button variant="outline" color="secondary">
          Zero
        </Button>
      </Badge>

      <Badge content={0} showZero color="secondary">
        <Button variant="outline" color="secondary">
          Zero, shown
        </Button>
      </Badge>

      {/* Nothing to count, but something to report. */}
      <Badge dot color="danger">
        <Button variant="outline" color="secondary">
          Dot
        </Button>
      </Badge>
    </div>
  );
}

Which corner, and how far in

placement is one word built out of two the library already has — top/bottom from NebaSide, start/end from NebaAlign. A corner is one decision, and splitting it into two props would let a caller write { vertical: 'left' }. Because it says start/end, the corner flips with the writing direction.

overlap is the shape of the thing underneath. A circle's corner is further from its centre than a square's, so a badge that looks right on an icon button hangs off an avatar.

import { Badge, Button } from 'neba';

const CORNERS = ['top-start', 'top-end', 'bottom-start', 'bottom-end'] as const;

export default function BadgePlacement() {
  return (
    <div className="flex flex-col gap-6">
      <div className="flex flex-wrap items-center gap-6">
        {CORNERS.map((placement) => (
          <Badge key={placement} placement={placement} content={3}>
            <Button variant="outline" color="secondary" size="lg">
              {placement}
            </Button>
          </Badge>
        ))}
      </div>

      {/* A circle's corner is further from its centre than a square's, so the
          badge has to tuck in further or it floats off the edge. */}
      <div className="flex flex-wrap items-center gap-6">
        {(['square', 'circle'] as const).map((overlap) => (
          <div key={overlap} className="flex items-center gap-3">
            <Badge overlap={overlap} content={3} color="danger">
              <span className="flex size-10 items-center justify-center rounded-full bg-(--n-soft-press) text-[0.8125rem] font-semibold text-(--neba-fg)">
                JD
              </span>
            </Badge>
            <span className="text-[0.75rem] text-(--neba-muted-fg)">overlap="{overlap}"</span>
          </div>
        ))}
      </div>
    </div>
  );
}

Sizes

import { Badge, Button } from 'neba';

const SIZES = ['xs', 'sm', 'md', 'lg', 'xl'] as const;

export default function BadgeSizes() {
  return (
    <div className="flex flex-col gap-5">
      <div className="flex flex-wrap items-center gap-6">
        {SIZES.map((size) => (
          <Badge key={size} size={size} content={12}>
            <Button size={size} variant="outline" color="secondary">
              {size}
            </Button>
          </Badge>
        ))}
      </div>
      <div className="flex flex-wrap items-center gap-6">
        {SIZES.map((size) => (
          <Badge key={size} size={size} dot color="success">
            <Button size={size} variant="outline" color="secondary">
              {size}
            </Button>
          </Badge>
        ))}
      </div>
    </div>
  );
}

A badge is the one thing allowed to be a pill

At 18px tall, --neba-radius-xs (10px) is already past the halfway point that would make a shape a pill. So Badge is the only component in the library that reaches for rounded-full.

That is not a hole in the design language, it is the exception the language names. The flat run along a sheet's top and bottom edge is what says "this is a cut surface". A badge is not a surface. It is a mark laid on one, and a mark has no edge to cut — which is also why it is the only component that overlaps its neighbour.

No transform

Every other library positions a corner badge with translate(50%, -50%). This one uses a negative margin of half the marker's own height. It costs two more lines, and the rule against transform is absolute and worth more than those two lines.

The side effect is not bad either. Vertically the overhang is exactly half; horizontally the pull is half the height rather than half the width, so a wide 99+ tucks in a little further than half — which is what you want anyway.

Accessibility

content={3} beside a bell is just "3" to a screen reader. label replaces it with the sentence.

<Badge content={3} label="3 unread notifications">
  <Button startIcon={<BellIcon />} aria-label="Notifications" />
</Badge>

Under a dot the count stays in the DOM — clipped rather than removed — because a quiet corner should not be a silent one. When the marker is invisible, or when there is no content to show, nothing is left behind at all: a mark that is not there has nothing to say, and text left in a clipped box is text a find-on-page still turns up.