useContactAvatar

A hook that resolves the correct avatar representation from a contact's details:

• Photo priority — When a photoID is present, it always takes precedence over name or icon, rendering an AvatarImage.
• Name resolution chain — When no photo is available, the hook resolves a display name in priority order: fullName → firstName/middleName/lastName → companyName → email. The resolved name is passed to Avatar so EDS auto-generates initials.
• Icon fallback — When no resolvable name exists (or the contact category is 'company'), the hook renders an AvatarIcon. Provide a custom avatarIcon prop to override the default ProfileIcon.
• HTML sanitization — Contact names are decoded and stripped of HTML/script tags before rendering to guard against XSS.
• "Unknown" contact handling — Contacts explicitly named 'unknown' or '#unknown' are treated as empty and fall through to the icon fallback.
• Separation of concerns — The hook returns plain name and children props ready to spread onto <Avatar>, so the hook is fully decoupled from sizing and styling decisions.

When photoID is present on the contact, the hook returns an AvatarImage as children. The image always takes priority over any name or icon.

const avatarProps = useContactAvatar({
	contactDetails: {
		fullName: 'John Doe',
		photoID: 'https://i.pravatar.cc/150?img=12',
		category: 'person',
	},
});

return <Avatar {...avatarProps} size="40" />;

When no photo is available, the hook resolves a display name from the contact. The EDS Avatar component automatically renders initials from the resolved name. Full name takes priority; individual name parts (firstName, middleName, lastName) are used as a fallback.

const avatarPropsFullName = useContactAvatar({
	contactDetails: { fullName: 'Jane Smith', category: 'person' },
});

const avatarPropsFirstLast = useContactAvatar({
	contactDetails: { firstName: 'Alice', lastName: 'Johnson', category: 'person' },
});

return (
	<Stack className="gap-4">
		<Avatar {...avatarPropsFullName} size="40" />
		<Avatar {...avatarPropsFirstLast} size="40" />
	</Stack>
);

When a contact has no personal name fields, the hook falls back to companyName for the avatar display.

const avatarProps = useContactAvatar({
	contactDetails: {
		companyName: 'ACME Corporation',
		category: 'person',
	},
});

return <Avatar {...avatarProps} size="40" />;

When neither name nor company name is available, the hook attempts to derive a display name from the contact's linkedContactMethods. The primary email is checked first, then non-primary email, and finally the login field. The extracted name is passed to Avatar for initials generation.

const avatarPropsEmail = useContactAvatar({
	contactDetails: {
		linkedContactMethods: [
			{ type: 'email', primary: true, value: 'john.doe@example.com' },
		],
		category: 'person',
	},
});

const avatarPropsLogin = useContactAvatar({
	contactDetails: {
		login: 'wane.smith@example.com',
		category: 'person',
	},
});

return (
	<Stack className="gap-4">
		<Avatar {...avatarPropsEmail} size="40" />
		<Avatar {...avatarPropsLogin} size="40" />
	</Stack>
);

When no resolvable name exists, the hook renders an AvatarIcon with the default ProfileIcon. This covers cases like empty contacts, contacts named 'unknown', or contacts with the 'company' category.

const avatarPropsEmpty = useContactAvatar({
	contactDetails: { category: 'person' },
});

const avatarPropsUnknown = useContactAvatar({
	contactDetails: { fullName: 'unknown', category: 'person' },
});

return (
	<Stack className="gap-4">
		<Avatar {...avatarPropsEmpty} size="40" />
		<Avatar {...avatarPropsUnknown} size="40" />
	</Stack>
);

Pass an avatarIcon function to override the default ProfileIcon used when no name can be resolved. The custom icon receives no props — it is a zero-argument function that returns a JSX element.

const avatarProps = useContactAvatar({
	contactDetails: { category: 'person' },
	avatarIcon: () => <ProfileIcon />,
});

return <Avatar {...avatarProps} size="40" />;

Our design system components include style props that allow you to easily customize different parts of each component to match your design needs.

Please refer to the Style API documentation for more insights.