Avatar

Installation

$ npx shadcn@latest add https://goodui.dev/native/r/avatar.json

Then run npx expo install --fix so react-native-reanimated, react-native-svg match your Expo SDK. Files land in components/goodui-native/avatar.

Usage

import { Avatar, AvatarGroup } from "@/components/goodui-native/avatar/avatar";

export function Assignees() {
  return (
    <>
      <Avatar name="Maya Patel" source="https://example.com/maya.jpg" size="lg" status="online" />
      <AvatarGroup
        max={3}
        people={[
          { name: "Maya Patel", source: "https://example.com/maya.jpg" },
          { name: "Leo Martins" },
          { name: "Aiko Tanaka" },
          { name: "Sam Okafor" },
        ]}
      />
    </>
  );
}

When to use

Examples

const refs = useRef<(ComponentRef<typeof View> | null)[]>([]);
const origin = useRef<ComponentRef<typeof View> | null>(null);

<Avatar
  ref={(el) => { refs.current[i] = el; }}
  name={user.name}
  source={user.avatar}
  size="lg"
  story={allSeen ? "seen" : "unseen"}
  onPress={() => { origin.current = refs.current[i]; setOpen(true); }}
/>
<Stories users={users} open={open} onClose={() => setOpen(false)} initialUser={i} originRef={origin} />

<Avatar name="Northwind" shape="square" source={logo} />

<AvatarGroup people={members} max={4} onPress={() => router.push("/members")} />

API reference

Motion and haptics

• •The photo fades in over the initials on the slow timing once it has loaded; a photo that fails to load leaves the initials.
• •Story ring: switching to unseen sweeps the accent arc around from twelve o'clock over 650 ms; switching to seen retracts it after a short beat, leaving the thin grey ring. Nothing animates on mount.
• •A pressable avatar sinks to 0.92 inside its ring on the snappy spring from touch down.
• •AvatarGroup fans out on the smooth spring; each avatar starts a beat after the one before it and lifts slightly at the middle of its travel, and the group's width follows on the UI thread.
• •The online dot can pulse (Badge pulse).
• •Reduced motion: the photo appears without fading, the ring crossfades instead of sweeping, there is no press sink, the group jumps between folded and fanned, and the dot does not pulse.

• •Haptic: tap when a pressable Avatar or AvatarGroup is pressed (configurable with haptic, false turns it off)

• •The fade, the ring sweep, the press and the fan run on the UI thread with Reanimated. The ring is one SVG circle whose dash offset animates; no re-renders while it moves.
• •Color from the name is a small string hash, computed during render with no state.

Accessibility

• •Without onPress an Avatar is an image labelled with the name, the status and 'new story' (for example 'Maya Patel, online, new story'); the initials and dot are not read separately.
• •With onPress it is a button with the same label and a 44 pt minimum touch target through hitSlop.
• •AvatarGroup is read as one element: 'Maya Patel, Leo Martins, Aiko Tanaka and 5 others'. When it fans out it is a button with the expanded state (aria-expanded on the web).
• •Initials keep their size at large text settings so they never clip; the name is in the label.
• •Initials sit on an accent family's soft fill in that family's accent color. Only families that keep 4.5:1 in light and dark are used (violet, blue, green, amber, orange).

Notes for AI

Related