KQ-510 · AVATAR/PICK

Avatar Pick

A face chooser where one ring travels between the tiles on snap, keyed by a shared layoutId so it is the same ring moving rather than nine rings blinking. The chosen face puffs to 1.08 on recoil while the rest lose a little saturation on a tween, and the last tile opens a real file picker and previews the image in place. Arrows step and wrap, Home and End jump to the ends, Space and Enter select.

KQ-510 · AVATAR/PICK

Choose a face

Waylight profile · Kestrel

Install

One command — the source lands in your repo. Or copy it from the Code tab.

$ pnpm dlx shadcn@latest add @kinetiq/avatar-pick

Props

options: AvatarOption[]; default —; The faces: an id, one or two initials, a tint (pass a theme token), and a label used as the accessible name.
value / defaultValue: string; default —; Controlled or initial id. The uploaded face reserves the id "upload".
onValueChange: (id: string) => void; default —; Fires on every choice, including the one an upload makes.
allowUpload: boolean; default true; Shows the tile that opens a real file picker and previews the chosen image.
label: React.ReactNode; default —; Visible group label. Omit it and pass aria-label to label the group invisibly.

Prop	Type	Default	Description
options	AvatarOption[]	—	The faces: an id, one or two initials, a tint (pass a theme token), and a label used as the accessible name.
value / defaultValue	string	—	Controlled or initial id. The uploaded face reserves the id "upload".
onValueChange	(id: string) => void	—	Fires on every choice, including the one an upload makes.
allowUpload	boolean	true	Shows the tile that opens a real file picker and previews the chosen image.
label	React.ReactNode	—	Visible group label. Omit it and pass aria-label to label the group invisibly.