Skip to Content
Documentation

User Format

Show a member's name in their role color, with the role's icon or emoji in front, an optional avatar and an optional link to their profile.

UserFormat prints a member's name the way the rest of the site does. Use it anywhere a name shows up: article bylines, tables, comments, notifications.

Preview

Usage

import { UserFormat } from '@vitnode/core/components/user-format'
<UserFormat format link user={user} />

format paints the name in the role's color and puts the role's prefix icon or emoji in front. link turns the name into a link to the member's profile at /users/<nameCode>. Without either, you get the plain name.

Avatar

Add avatar to put the member's face in front of the name. It's off by default, so names in running text stay plain.

<UserFormat avatar format link user={user} />

The avatar is 20px; set avatarSize for another size, such as 40 next to a page heading. It comes from user.avatarUrl. Without an upload, it's the first letter of nameCode on user.avatarColor (a hex color without #), and slate when the color is missing too. Most API responses about people already send both fields.

The avatar takes the place of the role's prefix icon or emoji, so a name never has both. With format, the name keeps the role color.

The image is decorative (alt=""), since the name right after it says who it is. With link, the avatar is part of the link.

Where the user comes from

user only needs a name and a role, so most API responses fit as they are:

const user = {
  name: 'Ada Lovelace',
  nameCode: 'ada',
  role: { color: '#dc2626', prefix: 'icon:crown' },
}

prefix takes the same icon:<lucide-name> or emoji:<emoji> value as a role's prefix in the AdminCP. A null color keeps the surrounding text color.

Real names

When a member turns on Show my real name in their settings, the API adds their first and last name as fullName, and UserFormat shows it instead of the nickname. While the switch is off, fullName is null and the real name never reaches the browser, so there is nothing to hide on the client.

const user = {
  fullName: 'Ada Lovelace',
  name: 'ada92',
  nameCode: 'ada92',
  role: { color: '#dc2626', prefix: 'icon:crown' },
}

People from the Content Engine already carry fullName. In your own API route, compute it with publicFullNameOf from @vitnode/core/lib/user-personal-information.

link needs a nameCode. Without one, the name renders as plain text.

Leave link off when the name sits inside another link or a button, such as a table row that already opens something. Nested links are invalid HTML and confuse screen readers.

Profile preview

A linked name opens a profile preview when someone rests the pointer on it or tabs to it. The card shows the member's cover, avatar with an online dot, name, @nameCode and primary role, then their reputation, how long ago they joined and when they were last here, with a View profile button at the bottom.

A profile preview card under a linked username, with cover, avatar with an online dot, name, role, reputation, join time, last visit and a View profile button

Phones and tablets have no hover, so there a tap opens the same preview as a bottom sheet. Swipe it down to close it, or tap View profile to go on to the profile.

The same profile preview as a bottom sheet on a phone, with a drag handle over the cover

Moderators also see the member's warnings in the preview: their active warning points, how many warnings are active and in total, and a Review link to the member's warnings in the ModCP. Everyone else never loads them.

You don't pass the preview any data. When it opens, it loads the member's public profile from GET /users/profile/{nameCode} and shows a skeleton until the answer arrives. The preview shares its cache with the profile page, so opening it and then going to the profile renders the page right away. Nothing is fetched for names nobody opens.

The preview is on by default for every UserFormat with link. Turn it off with preview={false} when the name already sits inside another hover card:

<UserFormat format link preview={false} user={user} />

Preview on an avatar

Wrap any element in UserPreview to give it the same preview. It renders a link to the profile (a button that opens the sheet on touch screens), so only pass the nameCode:

import { Avatar } from '@vitnode/core/components/avatar'
import { UserPreview } from '@vitnode/core/components/user-preview'

<UserPreview decorative nameCode={user.nameCode}>
  <Avatar alt="" size={32} user={user} />
</UserPreview>

Add decorative when a linked name sits right next to the avatar. It keeps the duplicate link out of the tab order and away from screen readers, while mouse and touch users still get the preview.

Names inside a sentence

UserFormat is an inline-flex row, which keeps the icon centered on the name. Don't override it with inline, or the icon drops to the text baseline. When the name sits in running text, add align-bottom so it lines up with the words around it:

<p>
  Written by <UserFormat className="align-bottom" format link user={user} />
</p>

Props

NameTypeRequiredDefaultDescription
user{ name, fullName?, nameCode?, avatarColor?, avatarUrl?, role: { color, prefix? } }Yes-The member to show
avatarbooleanNofalsePuts the avatar before the name, in place of the role prefix
avatarSizenumberNo20The avatar's width and height in pixels
formatbooleanNofalseAdds the role color and prefix
linkbooleanNofalseLinks to /users/<nameCode> when it is set
previewbooleanNotrueWith link, opens the profile preview (hover card, or bottom sheet on touch)
classNamestringNo-Extra classes on the outer element

Other <span> props go to the outer <span>. With link, only className, style and title reach the link.

See also

  • Role Format - the same look for a role on its own.
  • User - pick a member in an Auto Form field.