Avatar

Stable

User identity component with image, initials, icon, and custom fallback.

Installation

npm install @xaui/native

Import

import { Avatar } from '@xaui/native/avatar'

Basic Usage

Minimal example showing the component with its default configuration.

import { Avatar } from '@xaui/native/avatar'

export function Example() {
  return <Avatar />
}

With image

Use `src` to display a remote image.

import { Avatar } from '@xaui/native/avatar'

export function AvatarImageExample() {
  return (
    <Avatar
      src="https://i.pravatar.cc/150?u=john"
      size="lg"
    />
  )
}

Initials fallback

When `src` is absent, `name` generates initials automatically.

import { Avatar } from '@xaui/native/avatar'
import { Row } from '@xaui/native/view'

export function AvatarInitialsExample() {
  return (
    <Row spacing={8}>
      <Avatar name="John Doe" themeColor="primary" />
      <Avatar name="Alice Martin" themeColor="secondary" />
      <Avatar name="Bob" themeColor="success" />
    </Row>
  )
}

Custom initials

Override the default initials logic with `getInitials`.

import { Avatar } from '@xaui/native/avatar'

export function AvatarCustomInitialsExample() {
  return (
    <Avatar
      name="John Doe"
      getInitials={(name) => name.split(' ').map(n => n[0]).join('').toUpperCase()}
    />
  )
}

Sizes

Use `size` preset or pass a custom number.

import { Avatar } from '@xaui/native/avatar'
import { Row } from '@xaui/native/view'

export function AvatarSizesExample() {
  return (
    <Row spacing={8} crossAxisAlignment="center">
      <Avatar name="SM" size="sm" />
      <Avatar name="MD" size="md" />
      <Avatar name="LG" size="lg" />
      <Avatar name="XL" size={64} />
    </Row>
  )
}

Radius

Control the shape with `radius`.

import { Avatar } from '@xaui/native/avatar'
import { Row } from '@xaui/native/view'

export function AvatarRadiusExample() {
  return (
    <Row spacing={8}>
      <Avatar name="RN" radius="none" />
      <Avatar name="RS" radius="sm" />
      <Avatar name="RM" radius="md" />
      <Avatar name="RL" radius="lg" />
      <Avatar name="RF" radius="full" />
    </Row>
  )
}

Bordered

Add a ring with `isBordered`.

import { Avatar } from '@xaui/native/avatar'
import { Row } from '@xaui/native/view'

export function AvatarBorderedExample() {
  return (
    <Row spacing={8}>
      <Avatar src="https://i.pravatar.cc/150?u=1" isBordered themeColor="primary" />
      <Avatar src="https://i.pravatar.cc/150?u=2" isBordered themeColor="success" />
      <Avatar src="https://i.pravatar.cc/150?u=3" isBordered themeColor="danger" />
    </Row>
  )
}

Icon fallback

Use `icon` when you have no image and no name.

import { Avatar } from '@xaui/native/avatar'
import { UserIcon } from 'lucide-react-native'

export function AvatarIconFallbackExample() {
  return (
    <Avatar
      icon={<UserIcon size={20} color="#fff" />}
      themeColor="secondary"
      size="lg"
    />
  )
}

Custom fallback

Provide any ReactNode as fallback with `fallback`.

import { Avatar } from '@xaui/native/avatar'

export function AvatarCustomFallbackExample() {
  return (
    <Avatar
      showFallback
      fallback={
        <View style={{ width: '100%', height: '100%', backgroundColor: '#eee', alignItems: 'center', justifyContent: 'center' }}>
          <Typography style={{ fontSize: 10 }}>N/A</Typography>
        </View>
      }
    />
  )
}

Disabled

Apply a disabled appearance with `isDisabled`.

import { Avatar } from '@xaui/native/avatar'

export function AvatarDisabledExample() {
  return (
    <Avatar
      src="https://i.pravatar.cc/150?u=jane"
      isDisabled
    />
  )
}

Custom appearance

Fine-tune styles for the container, image, or text.

import { Avatar } from '@xaui/native/avatar'

export function AvatarCustomAppearanceExample() {
  return (
    <Avatar
      name="JD"
      customAppearance={{
        container: { borderWidth: 2, borderColor: '#6366f1' },
        text: { fontWeight: '700', fontSize: 18 },
      }}
      size="lg"
    />
  )
}