[Avatar] Add avatar component

docs/reference/generated/avatar-fallback.json

@@ -0,0 +1,20 @@
+{
+  "name": "AvatarFallback",
+  "description": "Rendered when the image fails to load or when no image is provided.\nRenders a `<span>` element.",
+  "props": {
+    "delay": {
+      "type": "number",
+      "description": "How long to wait before showing the fallback. Specified in milliseconds."
+    },
+    "className": {
+      "type": "string | (state) => string",
+      "description": "CSS class applied to the element, or a function that\nreturns a class based on the component’s state."
+    },
+    "render": {
+      "type": "React.ReactElement | (props, state) => React.ReactElement",
+      "description": "Allows you to replace the component’s HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+    }
+  },
+  "dataAttributes": {},
+  "cssVariables": {}
+}

docs/reference/generated/avatar-image.json

@@ -0,0 +1,20 @@
+{
+  "name": "AvatarImage",
+  "description": "The image to be displayed in the avatar.\nRenders an `<img>` element.",
+  "props": {
+    "onLoadingStatusChange": {
+      "type": "(status) => void",
+      "description": "Callback fired when the loading status changes."
+    },
+    "className": {
+      "type": "string | (state) => string",
+      "description": "CSS class applied to the element, or a function that\nreturns a class based on the component’s state."
+    },
+    "render": {
+      "type": "React.ReactElement | (props, state) => React.ReactElement",
+      "description": "Allows you to replace the component’s HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+    }
+  },
+  "dataAttributes": {},
+  "cssVariables": {}
+}

docs/reference/generated/avatar-root.json

@@ -0,0 +1,16 @@
+{
+  "name": "AvatarRoot",
+  "description": "Displays a user's profile picture, initials, or fallback icon.\nRenders a `<span>` element.",
+  "props": {
+    "className": {
+      "type": "string | (state) => string",
+      "description": "CSS class applied to the element, or a function that\nreturns a class based on the component’s state."
+    },
+    "render": {
+      "type": "React.ReactElement | (props, state) => React.ReactElement",
+      "description": "Allows you to replace the component’s HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+    }
+  },
+  "dataAttributes": {},
+  "cssVariables": {}
+}

docs/reference/overrides/avatar-image.json

@@ -0,0 +1,8 @@
+{
+  "name": "AvatarImage",
+  "props": {
+    "onLoadingStatusChange": {
+      "type": "(status) => void"
+    }
+  }
+}

docs/src/app/(public)/(content)/react/components/avatar/demos/hero/css-modules/index.module.css

@@ -0,0 +1,31 @@
+.Root {
+  display: inline-flex;
+  justify-content: center;
+  align-items: center;
+  vertical-align: middle;
+  border-radius: 100%;
+  user-select: none;
+  font-weight: 500;
+  color: var(--color-gray-900);
+  background-color: var(--color-gray-100);
+  font-size: 1rem;
+  line-height: 1;
+  overflow: hidden;
+  height: 3rem;
+  width: 3rem;
+}
+
+.Image {
+  object-fit: cover;
+  height: 100%;
+  width: 100%;
+}
+
+.Fallback {
+  align-items: center;
+  display: flex;
+  justify-content: center;
+  height: 100%;
+  width: 100%;
+  font-size: 1rem;
+}

docs/src/app/(public)/(content)/react/components/avatar/demos/hero/css-modules/index.tsx

@@ -0,0 +1,20 @@
+import * as React from 'react';
+import { Avatar } from '@base-ui-components/react/avatar';
+import styles from './index.module.css';
+
+export default function ExampleAvatar() {
+  return (
+    <div style={{ display: 'flex', gap: 20 }}>
+      <Avatar.Root className={styles.Root}>
+        <Avatar.Image
+          src="https://images.unsplash.com/photo-1543610892-0b1f7e6d8ac1?w=128&h=128&dpr=2&q=80"
+          width="48"
+          height="48"
+          className={styles.Image}
+        />
+        <Avatar.Fallback className={styles.Fallback}>LT</Avatar.Fallback>
+      </Avatar.Root>
+      <Avatar.Root className={styles.Root}>LT</Avatar.Root>
+    </div>
+  );
+}

docs/src/app/(public)/(content)/react/components/avatar/demos/hero/index.ts

@@ -0,0 +1,3 @@
+'use client';
+export { default as CssModules } from './css-modules';
+export { default as Tailwind } from './tailwind';

docs/src/app/(public)/(content)/react/components/avatar/demos/hero/tailwind/index.tsx

@@ -0,0 +1,23 @@
+import * as React from 'react';
+import { Avatar } from '@base-ui-components/react/avatar';
+
+export default function ExampleAvatar() {
+  return (
+    <div style={{ display: 'flex', gap: 20 }}>
+      <Avatar.Root className="inline-flex size-12 items-center justify-center overflow-hidden rounded-full bg-gray-100 align-middle text-base font-medium text-black select-none">
+        <Avatar.Image
+          src="https://images.unsplash.com/photo-1543610892-0b1f7e6d8ac1?w=128&h=128&dpr=2&q=80"
+          width="48"
+          height="48"
+          className="size-full object-cover"
+        />
+        <Avatar.Fallback className="flex size-full items-center justify-center text-base">
+          LT
+        </Avatar.Fallback>
+      </Avatar.Root>
+      <Avatar.Root className="inline-flex size-12 items-center justify-center overflow-hidden rounded-full bg-gray-100 align-middle text-base font-medium text-black select-none">
+        LT
+      </Avatar.Root>
+    </div>
+  );
+}

docs/src/app/(public)/(content)/react/components/avatar/page.mdx

@@ -0,0 +1,24 @@
+# Avatar
+
+<Subtitle>An easily stylable avatar component.</Subtitle>
+<Meta
+  name="description"
+  content="A high-quality, unstyled React avatar component that is easy to customize."
+/>
+
+<Demo path="./demos/hero" />
+
+## API reference
+
+Import the component and assemble its parts:
+
+```jsx title="Anatomy"
+import { Avatar } from '@base-ui-components/react/avatar';
+
+<Avatar.Root>
+  <Avatar.Image src="" />
+  <Avatar.Fallback>LT</Avatar.Fallback>
+</Avatar.Root>;
+```
+
+<Reference component="Avatar" parts="Root, Image, Fallback" />

docs/src/nav.ts

@@ -48,6 +48,10 @@ export const nav = [
         label: 'Alert Dialog',
         href: '/react/components/alert-dialog',
       },
+      {
+        label: 'Avatar',
+        href: '/react/components/avatar',
+      },
       {
         label: 'Checkbox',
         href: '/react/components/checkbox',

packages/react/package.json

@@ -29,6 +29,7 @@
     ".": "./src/index.ts",
     "./accordion": "./src/accordion/index.ts",
     "./alert-dialog": "./src/alert-dialog/index.ts",
+    "./avatar": "./src/avatar/index.ts",
     "./checkbox": "./src/checkbox/index.ts",
     "./checkbox-group": "./src/checkbox-group/index.ts",
     "./collapsible": "./src/collapsible/index.ts",

packages/react/src/avatar/fallback/AvatarFallback.test.tsx

@@ -0,0 +1,69 @@
+import * as React from 'react';
+import { Mock } from 'vitest';
+import { Avatar } from '@base-ui-components/react/avatar';
+import { describeConformance, createRenderer } from '#test-utils';
+import { useImageLoadingStatus } from '../image/useImageLoadingStatus';
+
+vi.mock('../image/useImageLoadingStatus');
+
+describe('<Avatar.Fallback />', () => {
+  const { render } = createRenderer();
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describeConformance(<Avatar.Fallback />, () => ({
+    render: (node) => {
+      return render(<Avatar.Root>{node}</Avatar.Root>);
+    },
+    refInstanceof: window.HTMLSpanElement,
+  }));
+
+  it('should not render the children if the image loaded', async () => {
+    (useImageLoadingStatus as Mock).mockReturnValue('loaded');
+
+    const { queryByTestId } = await render(
+      <Avatar.Root>
+        <Avatar.Image />
+        <Avatar.Fallback data-testid="fallback" />
+      </Avatar.Root>,
+    );
+
+    expect(queryByTestId('fallback')).to.equal(null);
+  });
+
+  it('should render the fallback if the image fails to load', async () => {
+    (useImageLoadingStatus as Mock).mockReturnValue('error');
+
+    const { queryByText } = await render(
+      <Avatar.Root>
+        <Avatar.Image />
+        <Avatar.Fallback>AC</Avatar.Fallback>
+      </Avatar.Root>,
+    );
+
+    expect(queryByText('AC')).to.not.equal(null);
+  });
+
+  describe('prop: delay', () => {
+    const { clock, render: renderFakeTimers } = createRenderer();
+
+    clock.withFakeTimers();
+
+    it('shows the fallback when the delay has elapsed', async () => {
+      const { queryByText } = await renderFakeTimers(
+        <Avatar.Root>
+          <Avatar.Image />
+          <Avatar.Fallback delay={100}>AC</Avatar.Fallback>
+        </Avatar.Root>,
+      );
+
+      expect(queryByText('AC')).to.equal(null);
+
+      clock.tick(100);
+
+      expect(queryByText('AC')).to.not.equal(null);
+    });
+  });
+});

packages/react/src/avatar/fallback/AvatarFallback.tsx

@@ -0,0 +1,91 @@
+'use client';
+import * as React from 'react';
+import PropTypes from 'prop-types';
+import { BaseUIComponentProps } from '../../utils/types';
+import { useComponentRenderer } from '../../utils/useComponentRenderer';
+import { useAvatarRootContext } from '../root/AvatarRootContext';
+import type { AvatarRoot } from '../root/AvatarRoot';
+
+/**
+ * Rendered when the image fails to load or when no image is provided.
+ * Renders a `<span>` element.
+ *
+ * Documentation: [Base UI Avatar](https://base-ui.com/react/components/avatar)
+ */
+const AvatarFallback = React.forwardRef<HTMLSpanElement, AvatarFallback.Props>(
+  function AvatarFallback(props: AvatarFallback.Props, forwardedRef) {
+    const { className, render, delay, ...otherProps } = props;
+
+    const { imageLoadingStatus } = useAvatarRootContext();
+    const [delayPassed, setDelayPassed] = React.useState(delay === undefined);
+
+    React.useEffect(() => {
+      let timerId: number | undefined;
+
+      if (delay !== undefined) {
+        timerId = window.setTimeout(() => setDelayPassed(true), delay);
+      }
+
+      return () => {
+        window.clearTimeout(timerId);
+      };
+    }, [delay]);
+
+    const state: AvatarRoot.State = React.useMemo(
+      () => ({
+        imageLoadingStatus,
+      }),
+      [imageLoadingStatus],
+    );
+
+    const { renderElement } = useComponentRenderer({
+      render: render ?? 'span',
+      state,
+      className,
+      ref: forwardedRef,
+      extraProps: otherProps,
+    });
+
+    const shouldRender = imageLoadingStatus !== 'loaded' && delayPassed;
+
+    return shouldRender ? renderElement() : null;
+  },
+);
+
+export namespace AvatarFallback {
+  export interface Props extends BaseUIComponentProps<'span', AvatarRoot.State> {
+    /**
+     * How long to wait before showing the fallback. Specified in milliseconds.
+     */
+    delay?: number;
+  }
+}
+
+export { AvatarFallback };
+
+AvatarFallback.propTypes /* remove-proptypes */ = {
+  // ┌────────────────────────────── Warning ──────────────────────────────┐
+  // │ These PropTypes are generated from the TypeScript type definitions. │
+  // │ To update them, edit the TypeScript types and run `pnpm proptypes`. │
+  // └─────────────────────────────────────────────────────────────────────┘
+  /**
+   * @ignore
+   */
+  children: PropTypes.node,
+  /**
+   * CSS class applied to the element, or a function that
+   * returns a class based on the component’s state.
+   */
+  className: PropTypes.oneOfType([PropTypes.func, PropTypes.string]),
+  /**
+   * How long to wait before showing the fallback. Specified in milliseconds.
+   */
+  delay: PropTypes.number,
+  /**
+   * Allows you to replace the component’s HTML element
+   * with a different tag, or compose it with another component.
+   *
+   * Accepts a `ReactElement` or a function that returns the element to render.
+   */
+  render: PropTypes.oneOfType([PropTypes.element, PropTypes.func]),
+} as any;

packages/react/src/avatar/image/AvatarImage.test.tsx

@@ -0,0 +1,17 @@
+import * as React from 'react';
+import { Avatar } from '@base-ui-components/react/avatar';
+import { describeConformance, createRenderer } from '#test-utils';
+
+describe('<Avatar.Image />', () => {
+  const { render } = createRenderer();
+  vi.mock('./useImageLoadingStatus', () => ({
+    useImageLoadingStatus: () => 'loaded',
+  }));
+
+  describeConformance(<Avatar.Image />, () => ({
+    render: (node) => {
+      return render(<Avatar.Root>{node}</Avatar.Root>);
+    },
+    refInstanceof: window.HTMLImageElement,
+  }));
+});