Pill

A lozenge that floats an in-progress status over the page. Use it for information that keeps updating: a recording timer, a build still running.

import { Pill } from 'neba';

<Pill startIcon={<DotIcon />} color="danger" title="Recording" />;

Props

Prop	Type	Default	Description
variantshared	'solid' | 'outline' | 'text'	'solid'	Weight of the surface, said the way a *control* says it: the surface takes the tint, as on Button and Chip
sizeshared	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	Height and type scale
colorshared	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'secondary'	Semantic colour role. `secondary` here rather than `primary`, because the object this shape is borrowed from is very nearly neutral black
densityshared	'default' | 'compact'	'default'	Padding only: never the height, never the type scale
elevationshared	0 | 1 | 2 | 3	2	Drop shadow depth. `2` against the `0` everything else defaults to, and not an inconsistency: a Pill is defined by not being part of the page, and a lozenge floating flat on the content it floats over reads as a mistake
startIcon	ReactNode	—	The leading slot: a glyph, an avatar, a status dot, a photo. It is given a square box of its own and clipped to a circle, so an `<img>` lands in it as readily as an icon does
title	ReactNode	—	The headline in the middle: what the pill is currently about. Centred, with generous room either side of it
description	ReactNode	—	The second line, under the title. One step down and one step lighter
endIcon	ReactNode	—	The trailing slot. Outside the pressable area, so it can be a control of its own
details	ReactNode	—	The second half, revealed when `expanded`. The pill grows downward into it rather than swapping to a different shape: one object saying more, which is the whole idea being borrowed
expanded	boolean	false	Whether `details` is showing
positionshared	'static' | 'sticky' | 'fixed'	'static'	How it sits in the page’s scroll. `fixed` pins it against the viewport and centres it horizontally, which is the arrangement this shape exists for
sideshared	'top' | 'bottom'	'top'	Which edge it is held against when `position` is not `static`
onClick	MouseEventHandler	—	Passing it makes the row a real button. `endIcon` stays outside it: a `<button>` inside a `<button>` is markup the browser rewrites on parse
children	ReactNode	—	The middle: a line of text, a pair of small readouts

Every native <div> attribute passes through except title, which here is the pill's headline rather than the browser's tooltip.

The row has three parts: startIcon on the leading edge, endIcon on the trailing one, and the middle (title, description and anything in children) centred between them with generous padding either side.

color defaults to secondary and elevation to 2: it is meant to float, so the shadow is on by default.

Examples

title and description

title is the line the pill is about and description is the line under it. Both are optional: a title on its own keeps the row one line tall and the shape a true stadium, and adding a description grows it into a rounded rectangle with the same corner.

import { Pill } from 'neba';

function DotIcon() {
  return (
    <svg viewBox="0 0 16 16" fill="none">
      <circle cx="8" cy="8" r="4" fill="currentColor" />
    </svg>
  );
}

/**
 * A title alone keeps the row one line tall, so the lozenge stays a stadium.
 * Adding a description grows it into a rounded rectangle with the same corner.
 */
export default function PillText() {
  return (
    <div className="flex flex-wrap items-center gap-4">
      <Pill startIcon={<DotIcon />} color="success" title="All systems normal" />

      <Pill
        startIcon={<DotIcon />}
        color="warning"
        title="Degraded"
        description="EU-west is slow"
      />
    </div>
  );
}

startIcon and endIcon

The leading slot is a square box clipped to a circle, so an <img> fills and crops it the way an avatar should. The trailing slot sits outside the pressable area, so it can hold a readout or a control of its own.

import { IconButton, Pill } from 'neba';

function PauseIcon() {
  return (
    <svg viewBox="0 0 16 16" fill="none" aria-hidden="true">
      <path d="M6 3.5v9M10 3.5v9" stroke="currentColor" strokeWidth="1.75" strokeLinecap="round" />
    </svg>
  );
}

/**
 * The leading slot takes an image as readily as a glyph — it is a square box
 * clipped to a circle, and the image fills and crops it. The trailing slot is
 * outside the pressable area, so a control can live there.
 */
export default function PillSlots() {
  return (
    <div className="flex flex-wrap items-center gap-4">
      <Pill
        variant="outline"
        color="primary"
        startIcon={<img src="/logo-32.png" alt="" />}
        title="Neba UI"
        description="1.0.0 published"
      />

      <Pill
        color="info"
        title="Deploying"
        description="build 8f2c1a"
        endIcon={
          <IconButton icon={<PauseIcon />} label="Pause" size="xs" variant="text" color="info" />
        }
      />
    </div>
  );
}

details and expanded

details grows a second area beneath the pill. expanded makes that controlled, and onClick attaches the toggle. It expands by animating its height, the same way an Accordion panel does.

import { useState } from 'react';
import { Pill, Typography } from 'neba';

function PlaneIcon() {
  return (
    <svg viewBox="0 0 16 16" fill="none">
      <path
        d="M2 8.5 14 3l-3.5 10-2.2-4.2L2 8.5Z"
        stroke="currentColor"
        strokeWidth="1.5"
        strokeLinejoin="round"
      />
    </svg>
  );
}

/**
 * The compact/expanded pair, which is the whole idea being borrowed. The pill
 * grows into its second half by animating a measured height — nothing is
 * transformed, so no text is ever resampled on the way.
 */
export default function PillExpandable() {
  const [expanded, setExpanded] = useState(false);

  return (
    <div className="flex flex-col items-start gap-3">
      <Pill
        startIcon={<PlaneIcon />}
        color="info"
        title="KE081 → ICN"
        description="Boards in 25 minutes"
        expanded={expanded}
        onClick={() => setExpanded(!expanded)}
        details={
          <div className="flex flex-col gap-1">
            <Typography level="caption">Gate B14 · seat 12A</Typography>
            <Typography level="caption">On time</Typography>
          </div>
        }
      />

      <Typography level="caption">Press the pill.</Typography>
    </div>
  );
}

The details area is inert while closed. Focus can still enter a zero-height element, so aria-hidden alone would leave a keyboard user tabbing into something invisible.

variant and size

As far as colour goes a Pill is a control rather than a container: like a Button or a Chip, the surface itself takes the colour.

import { Pill, Typography } from 'neba';

function DotIcon() {
  return (
    <svg viewBox="0 0 16 16" fill="none">
      <circle cx="8" cy="8" r="4" fill="currentColor" />
    </svg>
  );
}

const VARIANTS = ['solid', 'outline', 'text'] as const;
const SIZES = ['sm', 'md', 'lg'] as const;

/**
 * A Pill is a *control* as far as colour goes, not a container: its surface is
 * the thing being coloured, exactly as on a Button or a Chip.
 */
export default function PillVariants() {
  return (
    <div className="flex flex-col gap-5">
      <div className="flex flex-wrap items-center gap-3">
        {VARIANTS.map((variant) => (
          <Pill
            key={variant}
            variant={variant}
            color="primary"
            startIcon={<DotIcon />}
            title={variant}
          />
        ))}
      </div>

      <div className="flex flex-wrap items-center gap-3">
        {SIZES.map((size) => (
          <Pill
            key={size}
            size={size}
            color="success"
            startIcon={<DotIcon />}
            title={`size ${size}`}
          />
        ))}
      </div>

      <div className="flex flex-wrap items-center gap-3">
        <Pill density="compact" color="secondary" startIcon={<DotIcon />} title="compact" />
        <Pill elevation={0} color="secondary" startIcon={<DotIcon />} title="elevation 0" />
        <Typography level="caption">Density is padding; elevation is how far it floats.</Typography>
      </div>
    </div>
  );
}

position and side

The same vocabulary Toolbar uses. fixed pins it against the viewport and centres it horizontally with auto margins, so it stays centred under RTL.

<Pill
  position="fixed"
  side="top"
  startIcon={<BuildIcon />}
  color="info"
  title="Building — 2 of 7"
/>

When to use something else

• A token inside a run of content (a tag, a filter, a status) is a Chip.
• A bar of controls along the top of a page is a Toolbar.
• Something the reader has to wait on and cannot dismiss is an Overlay; something they can dismiss is a Toast.