Customization
You own the source file — tune appearance with props (no fork required for most tweaks). For brand-wide colours and radius, wrap your app in KitProvider; for one-off looks, use the style props below.
Design theme
Open Design theme on the live preview — accent, corner radius and font update every variant instantly (same as KitProvider in your app).
Variants
Use the variant chips on the preview to switch examples; each maps to a demo you can copy from the Code tab.
Style props
React Native style and typed slots like fieldStyle, plus optional root className when you use NativeWind or Uniwind (cnProps from kit).
- styles
- AvatarStyle[] · default all fourWhich styles to offer: "flat" | "ink" | "crayon" | "pencil" | "pixel". One style hides the tabs.
- accent
- string · default theme accentSelection ring, check badge and tab colour.
- style
- StyleProp<ViewStyle>Style for the root.
- className
- stringTailwind classes on the root when using NativeWind or Uniwind.
Map tokens from your design system on Bring your design system or read Theming for KitProvider and NativeWind / Uniwind setup.
Props
| Prop | Type | Default |
|---|---|---|
| Avatar.id Built-in avatar id, e.g. "flat-01" or "pencil-07". Unknown ids show a neutral placeholder. | string | null | — |
| Avatar.size Width and height in points. | number | 48 |
| Avatar.shape Tile shape (rounded follows the kit radius). | "circle" | "rounded" | "square" | "circle" |
| Avatar.backgroundColor Tile colour behind the character; "transparent" for none. | string | the avatar's pastel |
| Avatar.accessibilityLabel Screen-reader label. | string | "<name> avatar" |
| selectedAvatar Selected id (controlled). | string | null | — |
| defaultAvatar Initial id when uncontrolled. | string | — |
| onSelect Called with the id and its definition. | (id, avatar) => void | — |
| styles Which styles to offer: "flat" | "ink" | "crayon" | "pencil" | "pixel". One style hides the tabs. | AvatarStyle[] | all four |
| include Only these ids, in this order. | string[] | — |
| exclude Hide these ids. | string[] | — |
| maxAvatars Show at most this many. | number | — |
| columns Grid columns (phone / medium / expanded). | number | 4 / 6 / 8 |
| avatarSize Avatar size in the grid. | number | fills the column |
| shape Shape of the tiles, ring and preview. | "circle" | "rounded" | "square" | "circle" |
| backgroundColor One colour for every tile, or one per avatar. | string | (avatar) => string | each avatar's pastel |
| showTabs Style tabs: All, Flat, Ink, Crayon, Pencil, Pixel. | boolean | true with 2+ styles |
| layout Scrolling grid, or one swipeable row (avatarSize defaults to 64 there). | "grid" | "carousel" | "grid" |
| showPreview Large preview of the selection with its name, style and id. | boolean | true |
| emptyMessage Shown when the filters leave nothing. | string | "No avatars match these filters." |
| accent Selection ring, check badge and tab colour. | string | theme accent |
| haptics Selection tick. | boolean | true |
| style Style for the root. | StyleProp<ViewStyle> | — |
| className Tailwind classes on the root when using NativeWind or Uniwind. | string | — |
| AVATARS / getAvatar / filterAvatars The catalogue ({ id, name, style, background, component }), lookup by id, and the same filter the picker uses. | exports | — |
Behaviour & accessibility
- Artwork
- Every avatar is react-native-svg paths and rects: no PNGs, URLs or base64, so it works offline and looks the same on iOS, Android and web. Each style has its own 18 characters; ids are stable: flat-01…18, ink-01…18, crayon-01…18, pencil-01…18, pixel-01…18.
- Motion
- The selection ring and check badge spring in, tiles squish while pressed, and the preview pops when the choice changes. Category tabs slide their underline.
- Layout
- layout="grid" fills its width (4 columns on phones, 6 on medium, 8 on expanded screens unless you pass columns) and scrolls inside a bounded parent. layout="carousel" is one swipeable row.
- Reduced motion
- Press squish and the preview pop are skipped; the ring appears instantly.
- Haptics
- A selection tick when you pick an avatar or switch tabs. Turn off with haptics={false}.
- Screen readers
- The grid is a radio group; each tile reads its character's name and selected state. <Avatar> reads as an image labelled with the name.
FAQ
- How do I make an avatar picker in React Native?
- Use ExpoKit's Avatar Picker, a Pro component: with ExpoKit Pro, the ExpoKit CLI copies a ready-made avatar picker into your Expo or React Native app as plain TypeScript you can edit. It works on iOS, Android and web, and in Expo Go.
- Does Avatar Picker work in Expo Go?
- Yes. Avatar Picker runs in Expo Go on iOS and Android with no development build — its packages (
expo-haptics,react-native-svg) are all included in Expo Go. - How do I add Avatar Picker to my Expo app?
- With ExpoKit Pro, add it with the ExpoKit CLI: it copies the component's source into your app and installs
expo-haptics,react-native-svg, so the code is yours to change. The install command is on this page for Pro members. - Is Avatar Picker free?
- Avatar Picker is part of ExpoKit Pro. With a Pro plan, log the CLI in once (
npx @expokit/cli@latest login) and it installs the full source into your app. - Can I change how Avatar Picker looks?
- Yes. It takes its colours, radius and light / dark mode from
useKit(), so wrapping your app in<KitProvider accent radius>re-skins it with every other ExpoKit component. The code lives in your project, so you can also edit anything directly.