Skip to content
Merged
Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
bec3aa5
feat(bulma-ui): add Avatar, Avatars, and Badge components
bestaxbot Jul 8, 2026
3e2e44c
fix(bulma-ui): stop standalone Badge from being shifted by the corner…
bestaxbot Jul 8, 2026
872778e
fix(bulma-ui): coerce Avatars max to a non-negative integer
bestaxbot Jul 8, 2026
864deec
fix(bulma-ui): apply the five Avatar/Badge review-flagged bugs
bestaxbot Jul 9, 2026
f7f753f
feat(bulma-ui): add imageProps to Avatar
bestaxbot Jul 9, 2026
5b486cf
feat(bulma-ui): accept ReactNode content on Badge
bestaxbot Jul 9, 2026
1172d2e
feat(bulma-ui): add uniform shape, Avatars.Avatar static, and no-poin…
bestaxbot Jul 9, 2026
555141c
feat(bulma-ui): add spaced mode and numeric spacing to Avatars
bestaxbot Jul 9, 2026
10d5549
refactor(bulma-ui): make Avatar/Avatars/Badge SCSS register-vars conf…
bestaxbot Jul 9, 2026
d61344f
test(bulma-ui): fill Avatar/Avatars/Badge test and story gaps
bestaxbot Jul 9, 2026
34191d7
docs(docs): expand Avatar/Avatars/Badge pages per review
bestaxbot Jul 9, 2026
d625c85
docs(bulma-ui): add Avatar/Badge to the theming skill references
bestaxbot Jul 9, 2026
1a0273c
docs(docs): list Avatar, Avatars, and Badge on the components and hom…
bestaxbot Jul 9, 2026
b695637
docs(docs): move Avatar and Badge to Beyond Bulma on the home page
bestaxbot Jul 9, 2026
d68dfcf
style(bulma-ui): replace inline styles with Block + flex helpers in A…
bestaxbot Jul 9, 2026
614a483
style(docs): replace inline flex div with Block in Badge guide example
bestaxbot Jul 10, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
135 changes: 135 additions & 0 deletions bulma-ui/src/components/Avatar.stories.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,135 @@
import type { Meta, StoryObj } from '@storybook/react-vite';
import { Avatar } from './Avatar';
import { Icon } from '../elements/Icon';

const meta: Meta<typeof Avatar> = {
title: 'Components/Avatar',
component: Avatar,
tags: ['autodocs'],
parameters: {
docs: {
description: {
component:
'Represents a person or entity as a compact image, falling back automatically from a photo to initials to an icon.',
},
},
},
argTypes: {
src: { control: 'text' },
alt: { control: 'text' },
name: { control: 'text' },
initials: { control: 'text' },
size: {
control: 'select',
options: [
'16x16',
'24x24',
'32x32',
'48x48',
'64x64',
'96x96',
'128x128',
],
},
shape: {
control: 'select',
options: ['circle', 'rounded', 'square'],
},
color: {
control: 'select',
options: [
'primary',
'link',
'info',
'success',
'warning',
'danger',
'black',
'dark',
'light',
'white',
],
},
href: { control: 'text' },
},
};
export default meta;
type Story = StoryObj<typeof Avatar>;

export const Photo: Story = {
render: function PhotoExample() {
return (
<Avatar
src="https://bulma.io/assets/images/placeholders/128x128.png"
name="Ada Lovelace"
size="64x64"
/>
);
},
};

export const BrokenImageFallsBackToInitials: Story = {
render: function BrokenImageExample() {
return (
<Avatar src="https://example.invalid/missing.jpg" name="Grace Hopper" />
);
},
};

export const Initials: Story = {
render: function InitialsExample() {
return (
<div style={{ display: 'flex', gap: '0.75rem' }}>
<Avatar name="Ada Lovelace" />
<Avatar name="Grace Hopper" />
<Avatar name="Katherine Johnson" />
<Avatar initials="XY" color="info" />
</div>
);
},
};

export const IconFallback: Story = {
render: function IconExample() {
return <Avatar icon={<Icon name="user" />} color="info" shape="rounded" />;
},
};

export const DefaultFallback: Story = {
render: function DefaultFallbackExample() {
return <Avatar />;
},
};

export const Shapes: Story = {
render: function ShapesExample() {
return (
<div style={{ display: 'flex', gap: '0.75rem' }}>
<Avatar name="Circle Shape" shape="circle" />
<Avatar name="Rounded Shape" shape="rounded" />
<Avatar name="Square Shape" shape="square" />
</div>
);
},
};

export const Sizes: Story = {
render: function SizesExample() {
return (
<div style={{ display: 'flex', alignItems: 'center', gap: '0.75rem' }}>
<Avatar name="Ada Lovelace" size="16x16" />
<Avatar name="Ada Lovelace" size="24x24" />
<Avatar name="Ada Lovelace" size="32x32" />
<Avatar name="Ada Lovelace" size="48x48" />
<Avatar name="Ada Lovelace" size="64x64" />
<Avatar name="Ada Lovelace" size={20} />
</div>
);
},
};

export const Clickable: Story = {
render: function ClickableExample() {
return <Avatar name="Ada Lovelace" href="https://bestax.io" />;
},
};
251 changes: 251 additions & 0 deletions bulma-ui/src/components/Avatar.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,251 @@
import React, { useEffect, useRef, useState } from 'react';
import { classNames, usePrefixedClassNames } from '../helpers/classNames';
import { useBulmaClasses, BulmaClassesProps } from '../helpers/useBulmaClasses';

const avatarColors = [
'primary',
'link',
'info',
'success',
'warning',
'danger',
'black',
'dark',
'light',
'white',
] as const;

/** Valid color values for the Avatar component. */
export type AvatarColor = (typeof avatarColors)[number];

const autoAvatarColors: AvatarColor[] = [
'primary',
'link',
'info',
'success',
'warning',
'danger',
];

const avatarSizes = [
'16x16',
'24x24',
'32x32',
'48x48',
'64x64',
'96x96',
'128x128',
] as const;

/** Valid preset size values for the Avatar component. */
export type AvatarSize = (typeof avatarSizes)[number];

/** Valid shape values for the Avatar component. */
export type AvatarShape = 'circle' | 'rounded' | 'square';

/**
* Derives a small set of initials from a name (e.g. "Ada Lovelace" -> "AL").
*/
function getInitialsFromName(name: string): string {
const words = name.trim().split(/\s+/).filter(Boolean);
if (words.length === 0) return '';
// Iterate by code point (Array.from) so astral-plane characters (emoji, some
// CJK) don't get split into half surrogates.
if (words.length === 1) {
return Array.from(words[0]).slice(0, 2).join('').toUpperCase();
}
const first = Array.from(words[0])[0];
const last = Array.from(words[words.length - 1])[0];
return (first + last).toUpperCase();
}

/**
* Deterministically hashes a string to pick one of the auto avatar colors.
*/
function getAutoColor(name: string): AvatarColor {
let hash = 0;
for (let i = 0; i < name.length; i++) {
hash = (hash << 5) - hash + name.charCodeAt(i);
hash |= 0;
}
const index = Math.abs(hash) % autoAvatarColors.length;
return autoAvatarColors[index];
}

/**
* Default generic avatar icon shown when there is no image, name, initials, or icon.
*/
function DefaultAvatarIcon() {
return (
<svg viewBox="0 0 24 24" width="60%" height="60%" aria-hidden="true">
<path
fill="currentColor"
d="M12 12a5 5 0 1 0 0-10 5 5 0 0 0 0 10Zm0 2c-4.42 0-9 2.24-9 5v2a1 1 0 0 0 1 1h16a1 1 0 0 0 1-1v-2c0-2.76-4.58-5-9-5Z"
/>
</svg>
);
}

/**
* Props for the Avatar component.
*
* @property {string} [className] - Additional CSS classes to apply.
* @property {string} [src] - Image URL. On load error (or if absent), falls back to initials, then icon.
* @property {string} [alt] - Alternate text for the image (required for meaningful images).
* @property {string} [name] - Derives initials and a deterministic background color when no `src`/`initials` is shown.
* @property {string} [initials] - Explicit initials override (else derived from `name`).
* @property {React.ReactNode} [icon] - Final fallback rendered when there is no `src`, `name`, or `initials`.
* @property {AvatarSize | number} [size] - Preset size, or a pixel size when a number.
* @property {AvatarShape} [shape] - Avatar shape. Default `'circle'`.
* @property {AvatarColor} [color] - Background color for initials/icon avatars (else auto-derived from `name`).
* @property {React.ElementType} [as] - Element/component to render as. Defaults to `'a'` when `href` is set, else `'figure'`.
* @property {string} [href] - When set, renders the avatar as a link.
* @property {string} [target] - Anchor target (forwarded only when rendering a link).
* @property {string} [rel] - Anchor rel (forwarded only when rendering a link).
*/
export interface AvatarProps
extends
Omit<React.HTMLAttributes<HTMLElement>, 'color'>,
Omit<BulmaClassesProps, 'color'> {
className?: string;
src?: string;
alt?: string;
name?: string;
initials?: string;
icon?: React.ReactNode;
size?: AvatarSize | number;
shape?: AvatarShape;
color?: AvatarColor;
as?: React.ElementType;
href?: string;
target?: string;
rel?: string;
}

/**
* Avatar component for representing a person or entity as a compact image.
*
* Falls back automatically: `src` (image) -> initials (from `initials`/`name`) -> `icon` ->
* a generic default icon. Initials avatars get a stable auto background color derived from
* `name` unless `color` is set.
*
* @function
* @param {AvatarProps} props - Props for the Avatar component.
* @returns {JSX.Element} The rendered avatar element.
*
* @example
* <Avatar src="/users/ada.jpg" name="Ada Lovelace" size="64x64" />
* @example
* <Avatar name="Grace Hopper" />
*/
export const Avatar: React.FC<AvatarProps> = ({
className,
src,
alt,
name,
initials,
icon,
size,
shape = 'circle',
color,
as,
href,
target,
rel,
style,
...props
}) => {
// Tracks the src that failed to load (rather than a plain boolean) so a
// new src is shown again without needing an effect to reset the flag.
const [erroredSrc, setErroredSrc] = useState<string | undefined>(undefined);
const imgRef = useRef<HTMLImageElement>(null);

const { bulmaHelperClasses, rest } = useBulmaClasses(props);

const showImage = !!src && src !== erroredSrc;

// Catch images that failed before hydration: in SSR/static pages a broken
// image can finish loading before React attaches its onError, so it never
// fires. A complete image with no intrinsic width is a load failure.
useEffect(() => {
const img = imgRef.current;
if (img && img.complete && img.naturalWidth === 0) {
setErroredSrc(src);
}
}, [src]);

const resolvedInitials = initials
? initials.toUpperCase()
: name
? getInitialsFromName(name)
: '';
const showInitials = !showImage && !!resolvedInitials;
const showIcon = !showImage && !showInitials && !!icon;
const showDefaultIcon = !showImage && !showInitials && !showIcon;

const resolvedColor = color ?? (name ? getAutoColor(name) : undefined);

const isPresetSize = typeof size === 'string' && avatarSizes.includes(size);
const sizeStyle =
typeof size === 'number'
? { width: size, height: size, fontSize: size / 2.5 }
: undefined;

const avatarClasses = usePrefixedClassNames('avatar', {
[`is-${size}`]: isPresetSize,
[`is-${shape}`]: shape,
[`is-${resolvedColor}`]:
resolvedColor && !showImage && avatarColors.includes(resolvedColor),
});

const combinedClasses = classNames(
avatarClasses,
bulmaHelperClasses,
className
);

const initialsClass = usePrefixedClassNames('avatar-initials');

const Tag: React.ElementType = as ?? (href ? 'a' : 'figure');
const isInteractive = Tag === 'a' || Tag === 'button';

// Only forward link attributes when rendering an anchor or a custom (non-DOM)
// component; a plain `as="div"` must not receive a stray `href`/`target`/`rel`.
const isLinkLike = Tag === 'a' || typeof Tag !== 'string';
const linkProps = isLinkLike ? { href, target, rel } : {};

const a11yProps = showImage
? {}
: {
...(isInteractive ? {} : { role: 'img' as const }),
'aria-label': alt || name || 'Avatar',
};

return (
<Tag
className={combinedClasses}
style={{ ...sizeStyle, ...style }}
{...linkProps}
{...a11yProps}
{...rest}
>
{showImage && (
<img
ref={imgRef}
src={src}
alt={alt || name || ''}
onError={() => setErroredSrc(src)}
/>
)}
{showInitials && (
<span className={initialsClass}>{resolvedInitials}</span>
)}
{showIcon && icon}
{showDefaultIcon && <DefaultAvatarIcon />}
</Tag>
);
};

Avatar.displayName = 'Avatar';

export default Avatar;
Loading
Loading