UI Launch

🧑‍🎨 AvatarSelector

A bottom sheet template that allows users to visually choose an avatar from a list of available options.
Supports grouping, selection highlighting, and a confirmation action.

✅ When to use

Use AvatarSelector when you want to:

Provide a guided flow for selecting or updating a user avatar.
Display avatars grouped by categories (e.g., styles, collections, or themes).
Allow users to confirm their selection before applying changes.

🚫 When not to use

Avoid using AvatarSelector if:

You need inline avatar selection without a modal/bottom sheet.
The avatar list is extremely large (consider pagination or search).
You require editing or uploading new avatars (this template is for selection only).

📦 Import

import AvatarSelector from "@madefordevs1999/ui-launch-native/system/templates/AvatarSelector";

🧩 Usage

import { useState } from "react";
import AvatarSelector from "@madefordevs1999/ui-launch-native/system/templates/AvatarSelector";
import { AvatarChoice } from "@madefordevs1999/ui-launch-native/system/templates/AvatarSelector.types";

const avatars: AvatarChoice[] = [
  {
    id: "0",
    source: "https://i.imgur.com/pggITa9.png",
    group: { id: "0", name: "Animals" },
  },
  {
    id: "1",
    source: "https://i.imgur.com/pggITa9.png",
    group: { id: "a", name: "Men" },
  },
  {
    id: "2",
    source: "https://i.imgur.com/pggITa9.png",
    group: { id: "0", name: "Animals" },
  },
  {
    id: "3",
    source: "https://i.imgur.com/bVQRR6D.png",
    group: { id: "b", name: "Women" },
  },
  {
    id: "4",
    source: "https://i.imgur.com/bVQRR6D.png",
    group: { id: "b", name: "Women" },
  },
  {
    id: "5",
    source: "https://i.imgur.com/bVQRR6D.png",
    group: { id: "b", name: "Women" },
  },
  {
    id: "6",
    source: "https://i.imgur.com/bVQRR6D.png",
    group: { id: "b", name: "Women" },
  },
  {
    id: "7",
    source: "https://i.imgur.com/bVQRR6D.png",
    group: { id: "b", name: "Women" },
  },
  {
    id: "8",
    source: "https://i.imgur.com/bVQRR6D.png",
    group: { id: "b", name: "Women" },
  },
  {
    id: "9",
    source: "https://i.imgur.com/bVQRR6D.png",
    group: { id: "b", name: "Women" },
  },
  {
    id: "10",
    source: "https://i.imgur.com/bVQRR6D.png",
    group: { id: "b", name: "Women" },
  },
  {
    id: "11",
    source: "https://i.imgur.com/bVQRR6D.png",
    group: { id: "b", name: "Women" },
  },
];

const Example = () => {
  const [visible, setVisible] = useState(false);

  return (
    <>
      <Button text="Choose Avatar" onPress={() => setVisible(true)} />
      <AvatarSelector
        visible={visible}
        avatars={avatars}
        title="Select your avatar"
        description="Choose from the different categories"
        confirmSelectionText="Confirm selection"
        selectedAvatarId="3"
        onAvatarSelect={(id) => console.log("Avatar selected:", id)}
        onConfirmSelection={(id) => {
          console.log("Confirmed avatar:", id);
          setVisible(false);
        }}
        onDismiss={() => setVisible(false)}
      />
    </>
  );
};

Result

Props

Prop	Type	Default	Description
`avatars`	`Array<{ id: string; source: string; group: AvatarGroup; alternativeDescription?: string }>`	required	The list of avatars available for selection. Each avatar belongs to a group.
`confirmSelectionText`	`string`	required	The text displayed on the confirm button.
`onAvatarSelect`	`(avatarId: string) => void`	required	Callback when an avatar is selected.
`onConfirmSelection`	`(avatarId: string) => void`	`undefined`	Callback when the confirm button is pressed. Returns the selected avatar id.
`selectedAvatarId`	`string`	`undefined`	The initially selected avatar id.
`...rest`	`BottomSheetProps`	—	Additional props inherited from `BottomSheet` (e.g., `visible`, `onDismiss`).

Avatar Selector