@usenavii/react

A thin React component on top of @usenavii/core. Memoized; renders the engine output as a data-URI <img> so the SVG is treated as opaque by the browser.

Install

npm i @usenavii/react

@usenavii/core is bundled in; you don't install it separately unless you also use the engine directly.

Usage

import { Navii } from '@usenavii/react';

export function UserChip({ user }) {
  return (
    <Navii
      seed={user.id}
      size={48}
      title={user.name}
      animated
      className="rounded-full"
    />
  );
}

Props

Extends AvatarOptions (see core docs) plus:

Prop	Type	Description
`seed`	string	Required. See the seed rule.
`className`	string	Class applied to the `<img>` element.
`style`	CSSProperties	Standard React inline style on the `<img>`. Note: this is the React DOM `style`, not the engine's `StyleHint` — use `styleHint` below for engine-level bias.
`styleHint`	`'masc' \| 'femme' \| 'neutral'`	Engine-level style hint (biases seeded picks). Forwarded to `AvatarOptions.style`. Renamed in React to avoid collision with React's `style` prop.
`alt`	string	Alt text. Falls back to `title` if omitted.

<NaviiGroup> — overlapping stack

Wraps core's renderGroup(). Common for team rows, contributor lists, attendee piles. Width is computed from size, overlap, and max so the rendered <img> has correct intrinsic dimensions and doesn't shift on load.

import { NaviiGroup } from '@usenavii/react';

<NaviiGroup
  seeds={team.map((u) => u.id)}
  size={48}
  overlap={0.3}        // 0 = no overlap, 0.7 = heavy stack
  max={5}              // overflow collapses into a "+N" counter tile
  ring="#0a0a0b"       // border around each tile
/>

NaviiGroupProps

Prop	Type	Default	Description
`seeds`	string[]	—	Required. Empty array renders nothing.
`size`	number	64	Per-tile size in px.
`overlap`	number 0–0.7	0.3	Fraction of tile that overlaps previous.
`max`	number	all	Cap before showing a `+N` counter tile.
`ring`	string	`#ffffff`	Border color around each tile.
`tileBg`	string	`#ffffff`	Fill behind each tile (use `'transparent'` to skip).
`counterFill`	string	`#E5E7EB`	Background of the `+N` tile.
`counterInk`	string	`#374151`	Text color of the `+N` tile.
`paletteId` / `palette` / `mood` / `background` / `animated` / `packs` / `styleHint`	—		Forwarded to every tile. Same semantics as `<Navii>`.

Memoization

The component memoizes the data-URI on seed + all option props via useMemo. This runs on both the server (SSR) and client (hydration), so output is byte-identical between the two renders. Subsequent renders with unchanged props reuse the cached URI without re-running the engine.

If you're rendering a list, ensure your seeds are stable across renders (e.g. user.id, not idx + Date.now()) — otherwise every render rebuilds every avatar.

Re-exports

Top-level @usenavii/core exports re-exported for convenience: createAvatar, selectAvatar, renderAvatar, renderGroup, plus the types AvatarSpec, AvatarOptions, GroupOptions, MoodId, Palette.