Indicator

A small dot or pill that decorates another element — unread counts on icons, status dots on avatars, "new" markers on nav items. Wraps any single child without changing its layout.

stable
since v0.1.0
0.8 kB
feedback
status

Preview

Open

tsx

import { Box, Indicator } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <Indicator content="3" colorScheme="danger">
      <Box padding="3" background="bg.subtle" borderRadius="md">
        Inbox
      </Box>
    </Indicator>
  );
}

Dot variant

Set dot to drop the content and render a small filled dot — the right fit for “has activity” / online-status decorations on avatars and nav icons.

Preview

Open

tsx

import { Box, Indicator, Inline } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <Inline gap="6" padding="4" background="bg.subtle" borderRadius="md">
      <Indicator dot colorScheme="success" placement="bottom-end" aria-label="Online">
        <Box padding="3" background="bg.surface" borderRadius="full" width="48px" height="48px" />
      </Indicator>
      <Indicator dot colorScheme="warning" placement="bottom-end" aria-label="Away">
        <Box padding="3" background="bg.surface" borderRadius="full" width="48px" height="48px" />
      </Indicator>
      <Indicator dot colorScheme="neutral" placement="bottom-end" aria-label="Offline">
        <Box padding="3" background="bg.surface" borderRadius="full" width="48px" height="48px" />
      </Indicator>
    </Inline>
  );
}

Colour schemes

colorScheme accepts accent, success, warning, danger, info, neutral. Pair semantics with colour: danger for unread / critical, success for online, warning for attention, accent for new / featured.

Preview

Open

tsx

import { Box, Indicator, Inline } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <Inline gap="5" padding="4" background="bg.subtle" borderRadius="md">
      {(['accent', 'success', 'warning', 'danger', 'info', 'neutral'] as const).map((scheme) => (
        <Indicator key={scheme} content="3" colorScheme={scheme} aria-label={`${scheme} count`}>
          <Box padding="3" background="bg.surface" borderRadius="md">
            {scheme}
          </Box>
        </Indicator>
      ))}
    </Inline>
  );
}

Placement

placement accepts top-start, top-end (default), bottom-start, bottom-end. Use offset to nudge the indicator inward when it should sit inside the child rather than spilling over the edge.

Preview

Open

tsx

import { Box, Indicator, Inline } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <Inline gap="5" padding="4" background="bg.subtle" borderRadius="md">
      {(['top-start', 'top-end', 'bottom-start', 'bottom-end'] as const).map((placement) => (
        <Indicator key={placement} content="•" placement={placement} aria-label={placement}>
          <Box padding="3" background="bg.surface" borderRadius="md" width="80px">
            {placement}
          </Box>
        </Indicator>
      ))}
    </Inline>
  );
}

API

PropTypeDefaultDescription

content

ReactNode

—

Content rendered inside the badge. Omit for dot mode.

dot

boolean

false

Render as a bare coloured dot rather than a content badge.

placement

"top-start"|"top-end"|"bottom-start"|"bottom-end"

top-end

Corner the badge hugs. One of `top-start`, `top-end`, `bottom-start`, `bottom-end`.

offset

number

Inset offset in pixels. Positive values push the badge further outside the child.

invisible

boolean

—

Hide the badge entirely while preserving layout.

hideOn

((content: ReactNode) => boolean)

—

Predicate variant of `invisible`, evaluated against `content`.

colorScheme

neutral

Palette forwarded to the inner badge. One of `neutral`, `accent`, `success`, `warning`, `danger`, `info`.

variant

"solid"|"soft"|"outline"|"ghost"

solid

Visual style forwarded to the inner badge. One of `soft`, `solid`, `outline`, `ghost`.

size

"xs"|"sm"|"md"

Pixel scale forwarded to the inner badge.

icon

ReactNode

—

Icon rendered inside the badge alongside `content`.

children*

ReactElement<unknown, string | JSXElementConstructor<any>>

—

The element the indicator decorates. Exactly one React element.

aria-label

string

—

Override screen-reader label. When omitted and `content` is a string or number, the content is announced; in pure dot mode the indicator is marked decorative.

Recipes

Unread count on an icon button: <Indicator content={count} colorScheme="danger" hideOn={(c) => !c}><IconButton ... /></Indicator> — the hideOn predicate keeps the indicator off the DOM when the count is zero.
Avatar online status: <Indicator dot colorScheme="success" placement="bottom-end"><Avatar ... /></Indicator>.
Always pair counts with an aria-label describing the meaning so AT users get more than just the number.