AvatarSelect

Installation

pnpm dlx @docyrus/cli add @docyrus/rn-avatar-select

pnpm add @shopify/flash-list expo-image-picker (optional) expo-image-manipulator (optional)

The Image tab needs the optional peer expo-image-picker (npx expo install expo-image-picker); without it the tab shows an install hint. imageCrop="editor" additionally uses the native ImageEditor, which needs expo-image-manipulator to apply the crop.

Usage

import { AvatarSelect, type AvatarFieldValue } from '@/components/docyrus-native/avatar-select';

const [avatar, setAvatar] = useState<AvatarFieldValue>({ icon: null, color: null, image: null });

<AvatarSelect
  value={avatar}
  onChange={(value, payload) => setAvatar(value)}
/>

Field mapping + payload

Records often store the avatar in three columns. The mapping renames the keys of the payload passed to onChange / onCommit — the same contract as web.

import { extractAvatarValue } from '@/lib/docyrus/avatar-utils';

<AvatarSelect
  value={extractAvatarValue(record, { iconField: 'avatar_icon', colorField: 'avatar_color', imageField: 'avatar_image' })}
  iconField="avatar_icon"
  colorField="avatar_color"
  imageField="avatar_image"
  onCommit={(value, payload) => updateRecord(record.id, payload)}
  // payload → { avatar_icon: 'fal rocket', avatar_color: 'indigo-500', avatar_image: null }
/>

Uploading images

uploadImage receives the picked (and cropped) file and returns the stored value. Without it the local file URI is stored as image.signed_url.

<AvatarSelect
  value={avatar}
  imageCrop="editor"
  uploadImage={async (asset) => {
    const stored = await uploadFile(asset.uri, asset.fileName, asset.mimeType);

    return { id: stored.id, file_name: stored.name, signed_url: stored.url, file_type: asset.mimeType };
  }}
  onChange={setAvatar}
/>

• imageCrop="system" (default): the OS picker's own square crop (allowsEditing: true, aspect: [1, 1]).
• imageCrop="editor": picks without cropping, then shows the native ImageEditor with a 1:1 stencil.

Inline editor

<AvatarSelect value={avatar} editorDisplay="inline" size={48} onChange={setAvatar} />

Behaviour

• The colour palette is TAILWIND_AVATAR_COLORS — all 22 Tailwind families at levels 200 and 500 ('indigo-500', 'rose-200', …), identical to web, so values round-trip between platforms.
• The icon library switch covers Font Awesome (fal *) and Huge Icons (huge *). An empty search shows the featured set; a search matches up to 120 icons, rendered in a 6-column FlashList grid.
• The full icon catalog (lib/icon-libraries, ~11k names) is loaded lazily the first time the Icon tab is shown, so importing AvatarSelect does not parse it at start-up.
• The emoji list is native-only and searchable by keyword; it starts with web's emoji set.
• The initial tab is derived from the value: image → Image, emoji → Emoji, otherwise Icon + Color.

API Reference

AvatarFieldValue

AvatarImageValue

AvatarUploadAsset

Avatar utilities

lib/avatar-utils (installed with the component) is synced with web:

Differences from web

• The AI tab is not ported (it is disabled "coming soon" on web too).
• size is in points, not Tailwind spacing units.
• editorDisplay defaults to 'popover' (an ActionSheet — native's behaviour before the port); web defaults to 'inline'.
• uploadImage receives an AvatarUploadAsset instead of a File.
• Native adds a Clear action and a searchable emoji list.

i18n

ui.common.changeAvatar, ui.common.searchIconPlaceholder, ui.common.noIconsFound, ui.common.color (web keys) plus ui.avatarSelect.title, ui.avatarSelect.iconTab, ui.avatarSelect.emojiTab, ui.avatarSelect.imageTab, ui.avatarSelect.fontAwesome, ui.avatarSelect.hugeIcons, ui.avatarSelect.pickColor, ui.avatarSelect.searchEmojiPlaceholder, ui.avatarSelect.noEmojiFound, ui.avatarSelect.uploadAndCrop, ui.avatarSelect.uploadHint, ui.avatarSelect.pickerMissing, ui.avatarSelect.uploadFailed, ui.avatarSelect.squareAvatar, ui.avatarSelect.clear, ui.avatarSelect.done.

Type Exports