# Persona
Package: @mantine/core
Import: import { Persona } from '@mantine/core';
Description: Display a person identity: avatar, presence badge and stacked text lines

## Usage

`Persona` displays a person identity: an avatar, an optional presence badge and up to
four text lines. Use it in people pickers, contact lists, comment authors and profile headers:

```tsx
import { Persona } from '@mantine/core';

function Demo() {
  return (
    <Persona
      name="Vitaly Rtishchev"
      secondaryText="Creator of Mantine"
      tertiaryText="Local time 4:32 PM"
      avatar={{ src: image }}
       size="md" textPosition="after" textAlignment="start" presence="available"
    />
  );
}
```


## Avatar

`avatar` prop accepts [Avatar](https://alpha.mantine.dev/llms/core-avatar.md) props or a custom React node. When it is not set,
initials generated from the `name` prop are displayed. To render `Persona` without an avatar,
use the [presenceOnly](#presence-only) prop:

```tsx
import { Persona } from '@mantine/core';

function Demo() {
  return (
    <Persona
      name="Jane Doe"
      secondaryText="Product designer"
      presence={{ status: 'busy', outOfOffice: true }}
    />
  );
}
```


By default, the avatar color is generated from the `name` prop. Set `color` in the `avatar`
prop to override it:

```tsx
import { Avatar, Persona } from '@mantine/core';

function Demo() {
  return (
    <>
      {/* Avatar with an image */}
      <Persona name="Jane Doe" avatar={{ src: 'https://example.com/avatar.png' }} />

      {/* Avatar with initials and a custom color */}
      <Persona name="Jane Doe" avatar={{ color: 'blue' }} />

      {/* Custom avatar node, aria-hidden because the name is rendered next to it */}
      <Persona
        name="Jane Doe"
        avatar={
          <Avatar color="grape" aria-hidden>
            JD
          </Avatar>
        }
      />
    </>
  );
}
```

## Presence

Set `presence` prop to display a status badge on the avatar. It accepts a status string or
an object with `outOfOffice` and `processing` modifiers:

```tsx
import { Persona, SimpleGrid } from '@mantine/core';

const statuses = [
  'available',
  'away',
  'busy',
  'do-not-disturb',
  'offline',
  'out-of-office',
  'blocked',
  'unknown',
] as const;

function Demo() {
  return (
    <SimpleGrid cols={{ base: 1, xs: 2 }}>
      {statuses.map((status) => (
        <Persona
          key={status}
          name="Jane Doe"
          secondaryText={status}
          presence={status}
          labels={{ [status]: '' }}
        />
      ))}
    </SimpleGrid>
  );
}
```


```tsx
import { Persona } from '@mantine/core';

function Demo() {
  return (
    <>
      <Persona name="Jane Doe" presence="available" />
      <Persona name="Jane Doe" presence={{ status: 'available', outOfOffice: true }} />
      <Persona name="Jane Doe" presence={{ status: 'available', processing: true }} />
    </>
  );
}
```

## Presence only

Set `presenceOnly` prop to display the presence badge inline with the text, without an
avatar:

```tsx
import { Persona, Stack } from '@mantine/core';

function Demo() {
  return (
    <Stack gap="xs">
      <Persona name="API" secondaryText="All systems operational" presence="available" presenceOnly />
      <Persona name="Database" secondaryText="Degraded performance" presence="away" presenceOnly />
      <Persona name="CDN" secondaryText="Major outage" presence="busy" presenceOnly />
    </Stack>
  );
}
```


## Text lines

`Persona` renders up to four text lines. Long lines are truncated with an ellipsis:

```tsx
import { Persona } from '@mantine/core';

function Demo() {
  return (
    <Persona
      name="Vitaly Rtishchev"
      secondaryText="Creator of Mantine"
      tertiaryText="Remote, Berlin"
      quaternaryText="Local time 4:32 PM"
    />
  );
}
```

## Radius

Set `radius` prop to change the avatar `border-radius`, the presence badge follows the avatar
shape. With compound components, set `radius` on `Persona`, not on `Persona.Avatar`:

```tsx
import { Persona, Stack } from '@mantine/core';

function Demo() {
  return (
    <Stack>
      <Persona
        name="Vitaly Rtishchev"
        secondaryText="radius: 1000px (default)"
        avatar={{ src: image }}
        presence="available"
      />
      <Persona
        name="Vitaly Rtishchev"
        secondaryText="radius: xl"
        avatar={{ src: image }}
        presence="available"
        radius="xl"
      />
      <Persona
        name="Vitaly Rtishchev"
        secondaryText="radius: md"
        avatar={{ src: image }}
        presence="available"
        radius="md"
      />
      <Persona
        name="Vitaly Rtishchev"
        secondaryText="radius: 0"
        avatar={{ src: image }}
        presence="available"
        radius={0}
      />
    </Stack>
  );
}
```


## Polymorphic component

`Persona` is a [polymorphic component](https://alpha.mantine.dev/llms/guides-polymorphic.md), set `component` prop to render it
as a link or a button. A `button` root shrinks to its content, set `w="100%"` to stretch it:

```tsx
import { Persona } from '@mantine/core';

function Demo() {
  return (
    <Persona
      component="a"
      href="https://mantine.dev"
      name="Vitaly Rtishchev"
      secondaryText="Open profile"
      presence="available"
    />
  );
}
```

## Compound components

For full control over the layout, use `Persona.Avatar`, `Persona.Presence` and `Persona.Text`
compound components instead of the shorthand props. `level` prop of `Persona.Text` sets the
line importance, `1` is the person name:

```tsx
import { Persona } from '@mantine/core';

function Demo() {
  return (
    <Persona>
      <Persona.Avatar src={image} />
      <Persona.Presence presence="available" />
      <Persona.Text level={1}>Vitaly Rtishchev</Persona.Text>
      <Persona.Text level={2}>Creator of Mantine</Persona.Text>
    </Persona>
  );
}
```


## Example: people list

```tsx
import { Paper, Persona, PersonaPresenceValue, Stack } from '@mantine/core';

const members: { name: string; role: string; image: string; presence: PersonaPresenceValue }[] = [
  { name: 'Emily Johnson', role: 'Product manager', image: image1, presence: 'available' },
  { name: 'Kevin Gilbert', role: 'Frontend developer', image: image2, presence: 'do-not-disturb' },
  { name: 'Mary Smith', role: 'UX researcher', image: image3, presence: { status: 'busy', outOfOffice: true } },
  { name: 'Robert Wolf', role: 'Backend developer', image: image4, presence: 'offline' },
];

function Demo() {
  return (
    <Paper withBorder p="md" radius="md">
      <Stack gap="lg">
        {members.map((person) => (
          <Persona
            key={person.name}
            name={person.name}
            secondaryText={person.role}
            avatar={{ src: person.image }}
            presence={person.presence}
          />
        ))}
      </Stack>
    </Paper>
  );
}
```



#### Props

**Persona props**

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| avatar | ReactNode \| AvatarProps | - | `Avatar` props (`src`, `name`, `color`, `radius`, ...) or a custom node rendered in place of the avatar. `false`, `null` and `''` render the default avatar |
| children | React.ReactNode | - | Custom content, replaces the default composition built from shorthand props |
| labels | Partial<Record<"available" \| "away" \| "busy" \| "do-not-disturb" \| "offline" \| "out-of-office" \| "blocked" \| "unknown" \| "outOfOffice", string>> | - | Presence status labels announced by screen readers, for example `{ available: 'Verfügbar', outOfOffice: 'nicht im Büro' }`. Missing keys fall back to the default English labels, an empty string label renders no status text |
| name | string | - | Primary text, usually the person name. Also drives avatar initials and color when the avatar has no image |
| presence | PersonaPresenceValue | 'none' | Presence badge: a status string or a configuration object `{ status, outOfOffice, processing }`. Use `'none'` to hide the badge |
| presenceOnly | boolean | false | If set, only the presence badge is displayed inline with the text, without an avatar |
| quaternaryText | React.ReactNode | - | Fourth line of text |
| radius | MantineRadius \| number | - | Key of `theme.radius` or any valid CSS value to set the avatar `border-radius`, `1000px` by default |
| secondaryText | React.ReactNode | - | Second line of text, for example the person role |
| size | MantineSize | 'md' | Controls avatar and text sizes |
| tertiaryText | React.ReactNode | - | Third line of text, for example the person status |
| textAlignment | "center" \| "start" | 'start' | Text block alignment |
| textPosition | "before" \| "after" \| "below" | 'after' | Text placement relative to the avatar |

**Persona.Avatar props**

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| allowedInitialsColors | DefaultMantineColor[] | - | A list of colors that is used for autogenerated initials. By default, all default Mantine colors can be used except gray and dark. |
| alt | string | - | Image `alt` attribute, also used as `title` attribute for placeholder |
| autoContrast | boolean | - | If set, adjusts text color based on background color for `filled` variant |
| children | React.ReactNode | - | Avatar placeholder, displayed when `src={null}` or when the image cannot be loaded |
| color | DefaultMantineColor \| "initials" | 'gray' | Key of `theme.colors` or any valid CSS color |
| gradient | MantineGradient | theme.defaultGradient | Gradient configuration for `variant="gradient"` |
| imageProps | DetailedHTMLProps<ImgHTMLAttributes<HTMLImageElement>, HTMLImageElement> | - | Attributes passed down to `img` element |
| name | string | - | Name of the user. When `src` is not set, used to display initials and to generate color when `color="initials"` is set. |
| radius | MantineRadius \| number | '1000px' | Key of `theme.radius` or any valid CSS value to set border-radius |
| size | MantineSize \| number | 'md' | Width and height of the avatar, numbers are converted to rem |
| src | string \| null | - | Image url, if the image cannot be loaded or `src={null}`, then placeholder is displayed instead |

**Persona.Presence props**

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| labels | Partial<Record<"available" \| "away" \| "busy" \| "do-not-disturb" \| "offline" \| "out-of-office" \| "blocked" \| "unknown" \| "outOfOffice", string>> | - | Status labels announced by screen readers. Keys set here take precedence over the `labels` of the parent `Persona`, which take precedence over theme default `labels`. An empty string label renders no status text |
| presence | PersonaPresenceValue | - | Presence status string or configuration object |

**Persona.Text props**

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| children | React.ReactNode | - | Text content. String content is also set as `title` so the full text is available when the line is truncated |
| level | PersonaTextLevel | 1 | Text importance level. `1` is the primary line (person name), `2`–`4` are secondary lines |


#### Styles API

Persona component supports Styles API. With Styles API, you can customize styles of any inner element. Follow the documentation to learn how to use CSS modules, CSS variables and inline styles to get full control over component styles.

**Persona selectors**

| Selector | Static selector | Description |
|----------|----------------|-------------|
| root | .mantine-Persona-root | Root element |
| avatarWrapper | .mantine-Persona-avatarWrapper | Wrapper around the avatar and the presence badge |
| avatar | .mantine-Persona-avatar | Avatar element |
| presence | .mantine-Persona-presence | Presence badge element |
| body | .mantine-Persona-body | Wrapper around the text lines |
| text | .mantine-Persona-text | Text line element, level is controlled by the `data-level` attribute |

**Persona CSS variables**

| Selector | Variable | Description |
|----------|----------|-------------|
| root | --persona-gap | Controls gap between the avatar and the text |
| root | --persona-presence-size | Controls presence badge width and height |
| root | --persona-primary-fz | Controls primary text `font-size` |
| root | --persona-secondary-fz | Controls secondary, tertiary and quaternary text `font-size` |

**Persona data attributes**

| Selector | Attribute | Condition | Value |
|----------|-----------|-----------|-------|
| root | data-text-position | - | Value of `textPosition` prop |
| root | data-text-alignment | - | Value of `textAlignment` prop |
| root | data-presence-only | `presenceOnly` prop is set | - |
| presence | data-status | - | Resolved presence status, for example `available` or `busy`, unrecognized statuses resolve to `unknown` |
| presence | data-variant | - | `filled` for solid statuses, `outline` for ring statuses |
| presence | data-processing | Presence `processing` is set | - |
| text | data-level | - | Text line level, `1` for the primary line and `2`–`4` for secondary lines |
