{"slug":"avatar","title":"Avatar","description":"Using the avatar machine in your project.","contentType":"component","framework":"svelte","content":"An avatar represents a user profile picture. It displays an image or fallback\ncontent in a container.\n\nAvatar supports fallback text or elements when the image fails to load or when\nno image is provided.\n\n## Resources\n\n\n[Latest version: v1.39.1](https://www.npmjs.com/package/@zag-js/avatar)\n[Logic Visualizer](https://zag-visualizer.vercel.app/avatar)\n[Source Code](https://github.com/chakra-ui/zag/tree/main/packages/machines/avatar)\n\n\n\n## Installation\n\nInstall the avatar package:\n\n```bash\nnpm install @zag-js/avatar @zag-js/svelte\n# or\nyarn add @zag-js/avatar @zag-js/svelte\n```\n\n## Anatomy\n\nCheck the avatar anatomy and part names.\n\n> Each part includes a `data-part` attribute to help identify them in the DOM.\n\n\n\n## Usage\n\nImport the avatar package:\n\n```tsx\nimport * as avatar from \"@zag-js/avatar\"\n```\n\nThe avatar package exports two key functions:\n\n- `machine` - State machine logic.\n- `connect` - Maps machine state to JSX props and event handlers.\n\n> Pass a unique `id` to `useMachine` so generated element ids stay predictable.\n\nThen use the framework integration helpers:\n\n```svelte\n<script lang=\"ts\">\n  import * as avatar from \"@zag-js/avatar\"\n  import { useMachine, normalizeProps } from \"@zag-js/svelte\"\n\n  const id = $props.id()\n  const service = useMachine(avatar.machine, ({ id }))\n  const api = $derived(avatar.connect(service, normalizeProps))\n</script>\n\n<div {...api.getRootProps()}>\n  <span {...api.getFallbackProps()}>PA</span>\n  <img alt=\"PA\" src={src} {...api.getImageProps()} />\n</div>\n```\n\n### Listening for loading status changes\n\nWhen the image loads or fails, `onStatusChange` is invoked.\n\n```tsx {2}\nconst service = useMachine(avatar.machine, {\n  onStatusChange(details) {\n    // details => { status: \"error\" | \"loaded\" }\n  },\n})\n```\n\n### Updating the image source programmatically\n\nUse `api.setSrc` when the image source changes after mount.\n\n```tsx\napi.setSrc(nextSrc)\n```\n\n## Styling guide\n\nEach avatar part includes a `data-part` attribute you can target in CSS.\n\n```css\n[data-scope=\"avatar\"][data-part=\"root\"] {\n  /* Styles for the root part */\n}\n\n[data-scope=\"avatar\"][data-part=\"image\"] {\n  /* Styles for the image part */\n}\n\n[data-scope=\"avatar\"][data-part=\"fallback\"] {\n  /* Styles for the fallback part */\n}\n```\n\n## Creating a component\n\nCreate your avatar component by abstracting the machine into your own component.\n\n### Usage\n\n\n\n### Implementation\n\nUse the `splitProps` utility to separate the machine's props from the\ncomponent's props.\n\n\n\n## Methods and Properties\n\n### Machine Context\n\nThe avatar machine exposes the following context properties:\n\n**`onStatusChange`**\nType: `(details: StatusChangeDetails) => void`\nDescription: Functional called when the image loading status changes.\n\n**`ids`**\nType: `Partial<{ root: string; image: string; fallback: string; }>`\nDescription: The ids of the elements in the avatar. Useful for composition.\n\n**`id`**\nType: `string`\nDescription: The unique identifier of the machine.\n\n**`getRootNode`**\nType: `() => ShadowRoot | Node | Document`\nDescription: A root node to correctly resolve document in custom environments. E.x.: Iframes, Electron.\n\n**`dir`**\nType: `\"ltr\" | \"rtl\"`\nDescription: The document's text/writing direction.\n\n### Machine API\n\nThe avatar `api` exposes the following methods:\n\n**`loaded`**\nType: `boolean`\nDescription: Whether the image is loaded.\n\n**`setSrc`**\nType: `(src: string) => void`\nDescription: Function to set new src.\n\n**`setLoaded`**\nType: `VoidFunction`\nDescription: Function to set loaded state.\n\n**`setError`**\nType: `VoidFunction`\nDescription: Function to set error state.\n\n### Data Attributes\n\n**`Image`**\n\n**`data-scope`**: avatar\n**`data-part`**: image\n**`data-state`**: \"visible\" | \"hidden\"\n\n**`Fallback`**\n\n**`data-scope`**: avatar\n**`data-part`**: fallback\n**`data-state`**: \"hidden\" | \"visible\"","package":"@zag-js/avatar","editUrl":"https://github.com/chakra-ui/zag/edit/main/website/data/components/avatar.mdx"}