Persona

A persona is a coin and the details beside it. PrimaryText is the name, and what the coin shows falls back through three steps: the picture at ImageUrl, then the initials taken from the name, then a generic person icon when the name gives no initials to take. SecondaryText is the second line, usually the role.

Presence marks the dot on the coin with one of eight statuses. Online, Away, Busy and Dnd say the person is signed in; Offline, Blocked, OutOfOffice and Unknown say they are not reachable, each in its own way. The dot names itself to screen readers after its status, and PresenceTitles replaces those names - and the tooltip - with your own wording, one entry per status; PresenceTitle does the same for a single persona. PresenceIconNames puts a glyph inside the dot, and PresenceIconName does the same for a persona that only ever shows the one status. The dot is a quarter of the coin, so a coin under 40px across - by its Size or by a custom CoinSize - has no room left for a glyph and shows none.

With a glyph inside the dot (PresenceIconNames):

A single status, without a map of all eight (PresenceIconName):

Named for the reader (PresenceTitles) - hover the dot to see the tooltip:

With no picture the coin shows initials, taken from PrimaryText by the rule the rest of the industry settled on: two words give the first letter of each, three skip the middle one, and anything else gives the first letter alone. What a display name carries around those words is taken off first - a parenthesized aside, punctuation, an address written for a machine - and a name that has no letters in it at all, a phone number for instance, yields the person icon instead of two arbitrary numerals, unless AllowPhoneInitials says the numbers are the name. ImageInitials overrides all of it with exactly what you pass - and since the coin is sized for the two letters a name can yield, anything longer is stepped down to fit rather than clipped by it.

ShowInitialsUntilImageLoads fills the coin while the picture is on its way, and the initials stay when it never arrives:

CoinIconName puts an icon in the coin in place of the initials, which is how a persona stands for something that is not a person - a team, a room, a service account. Pass a BitIconInfo to CoinIcon instead to use an icon from outside the built-in set. The icon also stands in when a picture fails and the name gives no initials.

Unknown is the coin for a person nobody has been able to resolve. It takes precedence over the picture and the initials both, and shows a question mark that UnknownIconName - or UnknownIcon, for an icon from outside the built-in set - replaces with something else.

Shape decides the outline of the coin. Circular is the default and what a picture of a person belongs in; Rounded is the square most design systems reserve for entities rather than people - a team, a room, a service account; and Square takes the corners off entirely, for a logo or a tile that has to fill the coin edge to edge. The presence dot follows the corner out so it keeps clearing the coin. Squared is the older shorthand for Rounded, and a Shape of its own wins over it.

CoinVariant decides how the coin color is spent when there is no picture in it: Fill paints the whole coin, Outline keeps only the ring and the initials, and Text drops the ring too and leaves the initials alone on the page.

Active points at the one person a view is about - whoever is speaking, whoever wrote the message being read - without moving them out of the list they belong to. ActiveAppearance picks how: a Ring in the coin color, a Shadow under the coin, or RingShadow for both. The ring is separated from the coin by a gap cut in the page color, and both are a proportion of the coin rather than a constant, so they stay in scale across the size ramp; a persona sitting on a surface of its own retunes that gap with the --bit-prs-ring-gap-clr variable, and its width with --bit-prs-ring-gap and --bit-prs-ring-width. Inactive is the other half of the same idea: it shrinks the coin slightly and fades it back - by --bit-prs-inactive-scale and --bit-prs-inactive-opacity - which is what everyone who is not speaking looks like in a call grid. It stands down while Active is true, since a persona cannot be both at once.

On a surface of its own, with the gap cut in that surface instead of the page:

The speaker and everyone else (Active and Inactive):

Two different things can be clicked. OnActionClick adds a small button under the coin - ActionIconName and ActionButtonTitle dress it, and ActionTemplate replaces it outright. OnImageClick turns the whole coin into a button instead: it reveals the overlay labelled by ImageOverlayText, and is a real button element - announced as one, focusable, and answering Enter and Space without the page scrolling underneath it. The overlay belongs to the click rather than to the picture, so a coin carrying initials, an icon or the unknown glyph reveals it just the same. The action button sits at the foot of the coin and the presence dot in its trailing corner, so a persona can carry both. TabIndex reaches whichever control the coin has become, and Href makes it a link rather than a button - see Link.

Action button (hover, or tab to it, at the bottom of the coin):

Clickable coin (hover or focus it to reveal the overlay):

A clickable coin with no picture in it reveals the same overlay:

An empty ImageOverlayText leaves the coin a plain button with no veil over it, which is what a coin that opens a profile rather than changing the picture wants:

A whole action of your own (ActionTemplate):

IsEnabled set to false dims the coin, greys the texts and stops every click and key the persona would otherwise answer - the action button is disabled outright and a clickable coin leaves the tab order.

OnImageLoad and OnImageError report what became of the picture. The coin falls back to the initials by itself when the load fails, so the callbacks are there for logging it, or for reaching for a second source. The picture itself is never held back waiting for the load event: a statically rendered page has nothing attached to fire one, and a prerendered page can have the picture in the cache before it does.

ImageLoading decides when the browser fetches the picture: Lazy holds off until it is nearly in view, which is what a long list of people wants, and Eager fetches it straight away. ImageAttributes is where any other attribute of the img element goes - crossorigin, referrerpolicy, decoding, fetchpriority, draggable. ImageFadeIn holds the picture back until it has loaded and then fades it in, so a long list of faces arrives as something the eye can follow instead of popping in one picture at a time.

Faded in on arrival (ImageFadeIn) - hide the persona and show it again to watch the fade:

ImageSrcSet offers the browser several copies of the picture and ImageSizes tells it how much room the coin will take, so a retina screen gets the sharp copy and a phone does not download it. A set of candidates is a picture in its own right: ImageUrl is only the source the browser falls back to, and a coin given nothing but candidates still shows one instead of dropping to its initials. ImageAlt describes the picture itself; leave it unset and the picture is marked decorative, since the name beside it already says who this is.

Candidates alone, with no ImageUrl behind them:

Every text has a template beside it - PrimaryTextTemplate, SecondaryTextTemplate, TertiaryTextTemplate and OptionalTextTemplate - for when a line has to hold more than a string. ImageOverlayTemplate replaces the text of the overlay, and CoinTemplate replaces the contents of the coin outright, which is the way in for a picture the component would not otherwise know how to render.

Text and overlay templates:

Coin template:

AutoCoinColor picks the coin color by a stable hash, so the same person keeps the same color everywhere and two people in a list are told apart at a glance. What is hashed is CoinColorSeed when it is set - a user id or an address, which keeps the color from moving when the displayed name does, and keeps two people who share a name apart - and otherwise ImageInitials or PrimaryText. AutoCoinColors replaces the set the hash picks from - a palette of one pins every persona to that color, and one that leaves the semantic colors out keeps a list of people from reading as a list of statuses. An explicit CoinColor wins over all of it.

Both of these are the same person under a different display name, held together by CoinColorSeed:

Hashed out of a palette of your own (AutoCoinColors):

CoinColor takes precedence over AutoCoinColor when set explicitly:

Reversed puts the coin after the texts instead of before them, which is what a row aligned to the right edge of a panel wants. The presence dot moves to the other corner with it.

A persona is only as wide as it needs to be. FullWidth stretches it across its container instead, and the texts take everything the coin leaves - which is what finally gives a long name something to ellipsize against. Each of the four rows carries itself as a native tooltip so the clipped part can still be read; set ShowOverflowTooltip to false where the rows are known to be wide enough and the tooltip is only noise.

Href turns the coin into a real link, which is what an avatar that opens a profile is: it is announced as a link, answers Enter, and can be opened in a new tab, copied or previewed the way every other link on the page can - none of which a coin that only runs a handler can offer. Target picks the browsing context it opens in, and setting it to _blank adds rel="noopener" of its own accord unless a Rel of your own says otherwise. A coin that only navigates takes no Edit image veil - it is not offering to change the picture - so it is named after the person instead; pass ImageOverlayText to put one back. OnImageClick still fires alongside the navigation where both are given, and a disabled persona drops the href rather than pretending to be a link that goes nowhere.

In a new tab, with rel="noopener" added for you:

With a veil of its own (ImageOverlayText) and a click handler beside the navigation:

A disabled link coin keeps its place but goes nowhere:

CoinColor paints the coin from the general palette. It is what the initials, the coin icon and the overlay are drawn against, so the pairing of background and foreground comes from the theme and stays legible in both schemes.

Every icon of the persona - the action button, the presence glyphs, the coin icon and the unknown coin - accepts a BitIconInfo beside its name, which is what lets an icon come from FontAwesome, Bootstrap Icons or any other font instead of the built-in set.

FontAwesome action icon (hover over the image):

FontAwesome coin icon:

Bootstrap Icons presence icons:

Size runs from Size8, which is a presence dot and a name and no coin at all, up to Size120. The size also decides how many of the four texts there is room for: the secondary from 40 up, the tertiary from 72, the optional from 100. ShowSecondaryText puts the second line back on the sizes that leave no room for it, which is what a compact list of people with a role under each name wants. CoinSize overrides the coin with a pixel size of your own, and scales the initials, the presence dot and the glyph inside it along with it. HidePersonaDetails drops the texts and leaves the coin alone, which then names itself after the primary text for anyone who cannot see it - and a persona given no texts at all drops the column of its own accord, so the coin is not left trailing the gap that would have sat between them.

Size 8 Persona:

Size 24 Persona:

Size 32 Persona:

Size 40 Persona:

Size 48 Persona:

Size 56 Persona:

Size 72 Persona:

Size 100 Persona:

Size 120 Persona:

CoinSize 150:

CoinSize 150 with initials:

The second line on a size that has no room for it (ShowSecondaryText):

Style and Class reach the root element, while Styles and Classes reach every part of the persona by name - the coin container, the image, the initials, the presence dot, the overlay, the action button and each of the four text rows.

Component's Style & Class:

Styles & Classes:

Set Dir to Rtl to lay the persona out right to left. The coin moves to the right of the texts and the presence dot moves with it. A pair of Latin initials is written back to front so that the layout reads them in the right order, while initials taken from a right-to-left name are already in that order and are left as they are.