Перейти к основному содержанию

Обзор

Avatar отображает изображение с резервной первой буквой. Используйте его рядом с названием записи или внутри Chip. Его корневым элементом по умолчанию является презентационный span.

Использование

Если изображение отсутствует или не загружается, резервный вариант отображает первую букву имени после удаления пробелов в верхнем регистре. Для пустого имени отображается -. colorSeed выбирает стабильные цвета резервного варианта и по умолчанию использует name; используйте идентификатор записи, чтобы цвет оставался стабильным при изменении имени. Изображение и резервный вариант по умолчанию являются декоративными. name задаёт видимый инициал и цвета резервного варианта, не добавляя доступную метку. Если аватар является единственным представлением человека или записи, задайте imageProps={{ alt: name }}, чтобы добавить метку и для изображения, и для резервного варианта по умолчанию. Оставляйте аватар декоративным, если видимое имя или помеченный владелец уже предоставляют эту информацию. imageProps принимает полный набор свойств изображения, включая srcSet, sizes, crossOrigin, referrerPolicy, нативные события, refs и render. Его src переопределяет сокращённое свойство src. fallbackProps принимает полный набор свойств резервного варианта, включая delay, дочерние элементы, маркировку, refs и render. Пользовательский render резервного варианта определяет его семантику доступности; если он декоративный, явно задайте aria-hidden.

Скомпонуйте части

Используйте Avatar.Root, Avatar.Image и Avatar.Fallback, когда вы управляете структурой компонента. Root задаёт размер, форму и внешний вид резервного варианта; он не создаёт дочерние элементы или доступные метки.
Части используют общее состояние загрузки изображения Base UI. По умолчанию Image отображает img после успешной загрузки, а Fallback отображает span, пока изображение отсутствует, загружается или не удалось загрузить. delay откладывает первоначальное отображение резервного варианта на миллисекунды; значение по умолчанию — 0. Изменённый источник загружается повторно и может заменить текущее изображение или резервный вариант. Avatar.Image предоставляет onLoadingStatusChange со значениями статуса idle, loading, loaded и error. Колбэк запускается, когда Base UI сообщает об изменении статуса, отличного от idle; размонтирование части Image сбрасывает общее состояние корня на idle. Root, Image и Fallback принимают зависящие от состояния функции className, style и render с imageLoadingStatus; Image также предоставляет transitionStatus. Используйте keepMounted для Image, если отображаемое изображение должно загружаться на месте, в том числе с loading="lazy" или оптимизированным компонентом изображения. Перенаправляйте нативные атрибуты, события и ref из пользовательских рендереров изображений. Смонтированное изображение всё ещё может загружаться или завершиться ошибкой; проверяйте состояние загрузки, а не считайте его наличие признаком успеха. Рендерер front-компонента сейчас поддерживает путь предварительной загрузки по умолчанию с src. Его изображение-хост не получает srcSet, sizes, loading, decoding или referrerPolicy. Изменяющаяся пользовательская функция render с keepMounted может оставить декодированное изображение скрытым, поскольку worker не может прочитать состояние его завершения или размеры. Используйте там предварительную загрузку по умолчанию, пока эти возможности рендерера не станут доступны. Публичные типы AvatarRootProps, AvatarImageProps, AvatarFallbackProps, AvatarRootState, AvatarImageState, AvatarFallbackState и AvatarImageLoadingStatus экспортируются из twenty-ui/primitives/data-display. Refs указывают на отображаемый DOM-элемент: по умолчанию это span, img и span либо элемент, переданный через render.

Форма и внешний вид

shape принимает значения square, rounded-square или circle. Размеры: xs (12px), sm (14px), md (16px), lg (24px), xl (32px) и xxl (40px). И xl, и xxl используют резервный текст размером 16px. Прежний размер xl в 40px теперь называется xxl. Замените существующие использования size="xl" на size="xxl", если они должны оставаться размером 40px. variant="outline" добавляет границу к резервному варианту. Переопределения color, backgroundColor и borderColor настраивают резервный вариант, тогда как загруженное изображение сохраняет исходный вид.
icon имеет приоритет как над изображением, так и над резервной первой буквой. Сам значок декоративный, поэтому добавьте метку корневому элементу, если он передаёт информацию. pulsing анимирует непрозрачность и учитывает предпочтения уменьшенного движения.

Открыть профиль

Для действий скомпонуйте нативную кнопку. Она управляет фокусом, активацией клавишами Enter и Space и отключённым состоянием. Задайте доступное имя, соответствующее действию. Разместите onClick и disabled на отображаемой кнопке; сокращённый Avatar не имеет свойств onClick, disabled или nativeButton. Для навигации скомпонуйте якорь с href или ссылку маршрутизатора, сохраняющую семантику якоря. Нативные ссылки активируются клавишей Enter. Сохраняйте навигационное и отключённое поведение в ссылке или интерактивном компоненте, который вы компонуете.

Перенос кликабельных аватаров

Для действий скомпонуйте нативную кнопку через render, а для навигации — якорь или ссылку маршрутизатора. Перенесите onClick и disabled на этот элемент и удалите nativeButton. Задайте элементу полезное доступное имя и избегайте вложенных интерактивных элементов. Avatar.Root и другие явные части сохраняют полный контракт событий Base UI. Сокращённые аватары по умолчанию декоративны. name не задаёт имя изображению, резервному варианту или интерактивному элементу-владельцу. Используйте непустой imageProps.alt только в том случае, если аватар передаёт идентичность, которая ещё не указана видимым текстом или меткой элемента-владельца. При использовании явных частей самостоятельно задавайте альтернативный текст изображения и метки резервного варианта или декоративные атрибуты, а переведённый контент храните в приложении.

Свойства

Типы и значения по умолчанию генерируются из общедоступных типов компонента. Явные части принимают нативные атрибуты и обработчики событий. Сокращённый Avatar не включает onClick; задайте его элементу-владельцу, переданному через render.
string
Background color override for a first-letter fallback.
string
Border color override for the outline fallback.
string | ((state: AvatarRootState) => string | undefined)
CSS class applied to the element, or a function that returns a class based on the component’s state.
string
Text color override for a first-letter fallback.
string
Stable value used to choose fallback colors. Defaults to name.
AvatarFallbackProps
Complete Avatar.Fallback props, including caller-owned children, labeling, refs, render, and fallback delay in milliseconds.
ReactNode
Decorative icon rendered instead of the image and first-letter fallback. Give the root an accessible label when the icon conveys information.
AvatarImageProps
Complete Avatar.Image props, including native image attributes, refs, render, keepMounted, and onLoadingStatusChange. Alternative text defaults to an empty string. Supply a nonempty alt to label the image and default fallback.
string
Name used for the first-letter fallback and fallback colors. Does not add an accessible label.
boolean
по умолчанию:"false"
Animates the avatar opacity. Respects reduced-motion preferences.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, AvatarRootState>
Caller-supplied root element or renderer. Defaults to a presentational span. Compose a native button or link explicitly for interaction, and put its click handler and disabled state on that owner.
boolean
по умолчанию:"false"
Surrounds the avatar with a background-colored ring so overlapping avatars stay distinct.
"circle" | "rounded-square" | "square"
по умолчанию:"square"
Shape of the avatar and its fallback.
"lg" | "md" | "sm" | "xl" | "xs" | "xxl"
по умолчанию:"md"
Avatar size: xs (12px), sm (14px), md (16px), lg (24px), xl (32px), or xxl (40px).
string | null
Image URL. A missing or failed image shows the fallback. imageProps.src overrides this value.
CSSProperties | ((state: AvatarRootState) => CSSProperties | undefined)
Style applied to the element, or a function that returns a style object based on the component’s state.
"outline" | "soft"
по умолчанию:"soft"
Visual treatment of the fallback.

Avatar.Root

string
Background color override for a first-letter fallback.
string
Border color override for the outline fallback.
ReactNode
Caller-owned Image, Fallback, and other content.
string | ((state: AvatarRootState) => string | undefined)
CSS class applied to the element, or a function that returns a class based on the component’s state.
string
Text color override for a first-letter fallback.
string
Stable value used to choose fallback colors. Defaults to name.
string
Name used to choose fallback colors. Does not add children or accessible labels.
boolean
по умолчанию:"false"
Animates the avatar opacity. Respects reduced-motion preferences.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, AvatarRootState>
Caller-supplied root element or renderer. Defaults to a presentational span. Compose a native button or link explicitly for interaction, and put its click handler and disabled state on that owner.
boolean
по умолчанию:"false"
Surrounds the avatar with a background-colored ring so overlapping avatars stay distinct.
"circle" | "rounded-square" | "square"
по умолчанию:"square"
Shape of the avatar and its fallback.
"lg" | "md" | "sm" | "xl" | "xs" | "xxl"
по умолчанию:"md"
Avatar size: xs (12px), sm (14px), md (16px), lg (24px), xl (32px), or xxl (40px).
CSSProperties | ((state: AvatarRootState) => CSSProperties | undefined)
Style applied to the element, or a function that returns a style object based on the component’s state.
"outline" | "soft"
по умолчанию:"soft"
Visual treatment of the fallback.

Avatar.Image

string
Caller-owned alternative text. Use an empty string for decorative images.
string | ((state: AvatarImageState) => string | undefined)
CSS class applied to the element, or a function that returns a class based on the component’s state.
"" | "anonymous" | "use-credentials"
Native image cross-origin policy, also used during preloading.
boolean
по умолчанию:"false"
Keeps the image mounted and loads it in place. Loading and failed images stay hidden while Fallback is shown.
"eager" | "lazy"
Native eager or lazy loading. Use keepMounted for lazy loading.
((status: ImageLoadingStatus) => void)
Called when Base UI reports a loading, loaded, or error status. Shares that state with Root and Fallback.
"" | "no-referrer-when-downgrade" | "no-referrer" | "origin-when-cross-origin" | "origin" | "same-origin" | "strict-origin-when-cross-origin" | "strict-origin" | "unsafe-url"
Native image referrer policy, also used during preloading.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<DetailedHTMLProps<ImgHTMLAttributes<HTMLImageElement>, HTMLImageElement>, AvatarImageState>
Replaces the image. Preserve a native image and forward the supplied attributes, events, and ref.
string
Native responsive image sizes used with srcSet.
string
Image URL. Image renders after a successful load unless keepMounted is enabled.
string
Native responsive image source candidates.
CSSProperties | ((state: AvatarImageState) => CSSProperties | undefined)
Style applied to the element, or a function that returns a style object based on the component’s state.

Avatar.Fallback

ReactNode
Caller-owned fallback content, such as initials or an icon.
string | ((state: AvatarFallbackState) => string | undefined)
CSS class applied to the element, or a function that returns a class based on the component’s state.
number
по умолчанию:"0"
Milliseconds before the initial fallback is shown. Defaults to 0.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, AvatarFallbackState>
Replaces the fallback span. Forward the supplied props and ref, and provide its accessible label or decorative attributes.
CSSProperties | ((state: AvatarFallbackState) => CSSProperties | undefined)
Style applied to the element, or a function that returns a style object based on the component’s state.