Examples
Examples
Basic Usage
The Person Card only needs a few data points to render a fully functional card.
Best Practices:
- The name should be either the person’s full name or nickname.
- The name should use title-case.
- The name should not include emojis.
- The featured image should always be paired with a descriptive alternative text to support assistive technologies.
- The featured image should have a central focal point.
- The featured image should not contain text.
Extended Usage
The Person Card can optionally be extended with additional information.
Best Practices:
- The profile-image should show a portrait of the person.
- The profile-image should be a square (1:1 aspect ratio) image.
- The profile-image should not display a partially cropped head.
- For optimal quality on high-resolution displays, the profile-image should be 280px in dimension.
- Redirects to external profile pages should open in a new tab.
Cover
The full-bleed layout gives images more space, allowing action or torso shots to take center stage – ideal for creating stronger emotional impact by highlighting key moments or expressive imagery.
Best Practices:
- Use the cover variant when the feature image plays a central role in storytelling.
- Strengthen emotional impact and fan connection by allowing text to overlap imagery.
- Select visuals with clarity and space for legible overlapping text.
Preview Image
To improve the user experience, Person Cards can display preview images while waiting for the high-resolution featured image to be loaded.
Note: The example below demonstrates the rendering of the preview image only. In a production environment, a high-resolution _image_ would be set alongside.
Best practices:
- The preview-image should be a scaled version of the featured image with a maximum of 50px width
- To ensure meaningful content to be shown as fast as possible without any additional network requests, the preview-image should be provided as base64 encoded data URIs
Preview Video
A great way to turn the Person Card into an engaging teaser is to add a video that appears when hovered.
Best practices:
- Use a short video (max. 5 seconds) when available and relevant.
- The video should be visually consistent with the featured image and represent the person authentically.
- Avoid videos with abrupt transitions or flashing elements that could be disruptive.
Image Fallbacks
When no profile-image is available, the Person Card generates a fallback based on the initials of the first and last name of the person.
If the image property is not set, the Person Card will attempt to use profile-image as the featured image. If neither image nor profile-image is available, it falls back to image-preview, and finally to a default placeholder if no media is provided.
Responsive Image and Performance
A great way to balance client-side performance and responsive images is by using srcset in conjunction with sizes and loading attributes. Read more about responsive image best practices here: Image
With Number
Essential for displaying player identifiers in Person Cards, especially important in sports where the number is strongly associated with athletes.
Best practices:
- Include the person's jersey or starting number if it’s widely recognized or essential for identity.
- Use only official numbers — no internal IDs or placeholder values.
- Keep the number short and legible (typically 1–2 digits).
- Only include a number when it adds meaningful recognition or context.
Mode and Appearance
By default, Person Cards adapt to a light mode environment and use a light appearance by default. In a dark mode environment, we recommend changing the Person Card appearance to dark.
💡 Pro Tip
The appearance of a Person Card can be set using the appearance property or by nesting it into a cosmos-mode component. Read more about the Mode & Appearance concept.
Best practices:
- The appearance of the card should follow the mode of the environment.
- The card appears light in light environments and dark in dark environments.
- A light appearance may be used in dark environments for high-contrast purposes.
- A dark appearance should not be used in light environments.
Compact Layout
Person Cards support a compact layout for use cases with limited available space.
💡 Pro Tip
The Person Card's layout is a Responsive Properties and can be configured per breakpoint. Try out this example
Best Practices:
- Use 'normal' layout in vertical feeds, standalone cards, or featured contexts.
- Use 'compact' layout in horizontal rails or narrow UIs.
- All Person Cards in a group should use the same layout value.
Make it favoritable
Persons can be favorited by users – while the favoritable button will be persistently displayed on touch-based devices, the button will only show up on hover on devices with pointer-based inputs.
Clicking on the favoritable button won't propagate the click event to the card component and won’t interfere with link redirection.
Best practices:
- The state of whether the person has been favorited or not has to be managed outside the component.
- If the Button uses a label, it should reflect the current state:
- When not favorited it should describe the action (e.g., "Follow").
- When favorited, it should reflect the state (e.g., "Following").
- The Buttons aria-label should always describe the action based on current follow state.
Listen to Resize Events
When initially mounting and whenever the media container of the Person Card resizes, the card emits a mediaresize event including the media's width and height.
A common use case is to update the image to make it perfectly fit the available space.
Best Practices:
- Only enable the observe-media-resize when needed.