Panoramica
Avatar mostra un’immagine con un’alternativa basata sulla prima lettera. Usalo accanto al nome di un record o all’interno di un Chip. La relativa radice predefinita è uno span di presentazione.
Utilizzo
-. colorSeed sceglie colori alternativi stabili e per impostazione predefinita usa name; usa un identificatore di record per mantenere stabile il colore quando il nome cambia.
L’immagine e il fallback predefinito sono decorativi. name fornisce l’iniziale visiva e i colori del fallback senza aggiungere un’etichetta accessibile. Quando l’avatar è l’unica rappresentazione di una persona o di un record, imposta imageProps={{ alt: name }} per etichettare sia l’immagine sia il fallback predefinito. Mantieni l’avatar decorativo quando un nome visibile o un proprietario etichettato fornisce già tali informazioni.
imageProps accetta il contratto completo dell’immagine, inclusi srcSet, sizes, crossOrigin, referrerPolicy, eventi nativi, ref e render. Il relativo src sovrascrive l’abbreviazione src. fallbackProps accetta il contratto completo del fallback, inclusi delay, elementi figlio, etichettatura, ref e render. Un render di fallback personalizzato gestisce la propria semantica di accessibilità; imposta esplicitamente aria-hidden quando è decorativo.
Componi le parti
UsaAvatar.Root, Avatar.Image e Avatar.Fallback quando gestisci l’anatomia. Root fornisce dimensione, forma e aspetto del fallback; non genera elementi figlio né etichette accessibili.
img dopo un caricamento riuscito e Fallback esegue il rendering di uno span mentre l’immagine è assente, in caricamento o non è stata caricata. delay posticipa la visualizzazione iniziale del fallback in millisecondi e il valore predefinito è 0. Una sorgente modificata viene caricata nuovamente e può sostituire l’immagine o il fallback correnti.
Avatar.Image espone onLoadingStatusChange con i valori di stato idle, loading, loaded e error. Il callback viene eseguito quando Base UI segnala una modifica di stato diversa da inattiva; lo smontaggio della parte Image reimposta lo stato della radice condivisa su idle. Root, Image e Fallback accettano funzioni className, style e render consapevoli dello stato con imageLoadingStatus; Image espone anche transitionStatus.
Usa keepMounted su Image quando l’immagine renderizzata deve essere caricata in posizione, incluso loading="lazy" o un componente immagine ottimizzato. Inoltra attributi nativi, eventi e la ref dai renderer di immagini personalizzati. Un’immagine montata può comunque essere in caricamento o non essere stata caricata; controlla lo stato di caricamento anziché considerare la sua presenza come un successo.
Il renderer del componente front supporta attualmente il percorso di precaricamento predefinito con src. L’immagine host non riceve srcSet, sizes, loading, decoding o referrerPolicy. Una funzione render personalizzata variabile con keepMounted può lasciare nascosta un’immagine decodificata perché il worker non può leggerne lo stato di completamento o le dimensioni. Usa il precaricamento predefinito in quel caso finché tali funzionalità del renderer non saranno disponibili.
I tipi pubblici AvatarRootProps, AvatarImageProps, AvatarFallbackProps, AvatarRootState, AvatarImageState, AvatarFallbackState e AvatarImageLoadingStatus sono esportati da twenty-ui/primitives/data-display. Le ref puntano all’elemento DOM sottoposto a rendering: span, img e span per impostazione predefinita, oppure l’elemento fornito tramite render.
Forma e aspetto
shape accetta square, rounded-square o circle. Le dimensioni sono xs (12px), sm (14px), md (16px), lg (24px), xl (32px) e xxl (40px). Sia xl sia xxl usano testo di fallback da 16px.
La precedente dimensione xl da 40px ora è xxl. Aggiorna gli utilizzi esistenti di size="xl" a size="xxl" quando devono rimanere a 40px.
variant="outline" aggiunge un bordo all’alternativa. Gli override color, backgroundColor e borderColor personalizzano l’alternativa, mentre un’immagine caricata mantiene il suo aspetto originale.
icon ha la precedenza sia sull’immagine sia sull’alternativa basata sulla prima lettera. L’icona stessa è decorativa, quindi etichetta la radice quando trasmette informazioni. pulsing anima l’opacità e rispetta le preferenze di riduzione del movimento.
Apri un profilo
onClick e disabled nel pulsante renderizzato; l’Avatar abbreviato non ha prop onClick, disabled o nativeButton.
Per la navigazione, componi un’ancora con un href o un link del router che preservi la semantica dell’ancora. I link nativi si attivano con Invio. Mantieni la navigazione e il comportamento disabilitato con il link o il componente interattivo che componi.
Migra gli avatar selezionabili
Componi un pulsante nativo tramiterender per le azioni, oppure un’ancora o un link del router per la navigazione. Sposta onClick e disabled su tale proprietario e rimuovi nativeButton. Assegna al proprietario un nome accessibile utile ed evita di annidare elementi interattivi. Avatar.Root e le altre parti esplicite mantengono il contratto completo degli eventi di Base UI.
Gli avatar abbreviati sono decorativi per impostazione predefinita. name non assegna un nome all’immagine, al fallback o al proprietario interattivo. Usa un imageProps.alt non vuoto solo quando l’avatar trasmette un’identità non già fornita da testo visibile o da un’etichetta del proprietario. Con parti esplicite, fornisci personalmente il testo alternativo dell’immagine e le etichette del fallback o gli attributi decorativi e mantieni i contenuti tradotti nella tua applicazione.
Props
I tipi e i valori predefiniti vengono generati dai tipi pubblici del componente. Le parti esplicite accettano attributi nativi e gestori di eventi. L’Avatar abbreviato ometteonClick; forniscilo al proprietario passato tramite 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
predefinito:"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
predefinito:"false"
Surrounds the avatar with a background-colored ring so overlapping avatars stay distinct.
"circle" | "rounded-square" | "square"
predefinito:"square"
Shape of the avatar and its fallback.
"lg" | "md" | "sm" | "xl" | "xs" | "xxl"
predefinito:"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"
predefinito:"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
predefinito:"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
predefinito:"false"
Surrounds the avatar with a background-colored ring so overlapping avatars stay distinct.
"circle" | "rounded-square" | "square"
predefinito:"square"
Shape of the avatar and its fallback.
"lg" | "md" | "sm" | "xl" | "xs" | "xxl"
predefinito:"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"
predefinito:"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
predefinito:"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
predefinito:"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.