An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
'use client';
/**
* @file Token.tsx
* @input Uses React, ReactNode, StyleXStyles
* @output Exports Token component, TokenProps, TokenColor, TokenColorMap types
* @position Core implementation; consumed by index.ts, tested by Token.test.tsx
*
* SYNC: When modified, update these files to stay in sync:
* - /packages/core/src/Token/TokenLink.tsx (interactive wrapper for href+onRemove)
* - /packages/core/src/Token/Token.doc.mjs (props table, features, implementation notes)
* - /packages/core/src/Token/Token.test.tsx (tests for new/changed behavior)
* - /packages/core/src/Token/index.ts (exports if types change)
* - /apps/storybook/stories/Token.stories.tsx (storybook stories)
* - /packages/cli/assets/templates/blocks/components/Token/ (showcase blocks)
*/
import {use, type ReactNode} from 'react';
import * as stylex from '@stylexjs/stylex';
import {
colorVars,
spacingVars,
radiusVars,
sizeVars,
durationVars,
easeVars,
fontWeightVars,
typeScaleVars,
} from '../theme/tokens.stylex';
import {Icon} from '../Icon';
import {mergeProps} from '../utils';
import {useLinkComponent} from '../Link/useLinkComponent';
import {useInteractiveRole} from '../hooks/useInteractiveRole';
import {TokenLink} from './TokenLink';
import type {BaseProps} from '../BaseProps';
import {themeProps} from '../utils/themeProps';
import {focusOutlineProps} from '../utils/focusOutline.stylex';
import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
import {usePressFeedback} from '../hooks/usePressFeedback';
import {cancelNestedTouchPress} from '../hooks/useClickableContainer';
import type {TokenColorMap} from './index';
import {disabledInteractionProps} from '../utils/disabledInteraction';
import {TokenNamingContext} from './TokenNamingContext';
import {
registerEnglishFallback,
useComponentTranslator,
} from '../i18n/useComponentTranslator';
import english from '../i18n/generated-english/Token/Token.generated';
registerEnglishFallback(english);
// =============================================================================
// Types
// =============================================================================
/**
* Token color type derived from TokenColorMap.
* Extensible via module augmentation of TokenColorMap.
*/
export type TokenColor = keyof TokenColorMap;
export type TokenSize = 'sm' | 'md' | 'lg';
export interface TokenProps extends BaseProps<HTMLElement> {
/** Ref forwarded to the root element */
ref?: React.Ref<HTMLElement>;
/**
* The text label displayed in the token.
*/
label: string;
/**
* The size of the token.
* @default 'md'
*/
size?: TokenSize;
/**
* The color variant of the token.
* @default 'default'
*/
color?: TokenColor;
/**
* Optional icon to display before the label.
*/
icon?: ReactNode;
/**
* Whether the token is disabled.
* @default false
*/
isDisabled?: boolean;
/**
* Callback when the remove (X) button is clicked.
* When provided, a remove button is rendered.
*/
onRemove?: (e: React.MouseEvent) => void;
/**
* Click handler. When provided, the token renders as a `<span>` container
* with an invisible `<button>` inside for accessibility.
*/
onClick?: (e: React.MouseEvent) => void;
/**
* Link URL. When provided, the token renders as an `<a>`.
*/
href?: string;
/**
* Accessible description for the token.
*/
description?: string;
/**
* Content rendered after the label (before the remove button, if present).
*/
endContent?: ReactNode;
/**
* Whether to visually hide the label (still accessible to screen readers).
* @default false
*/
isLabelHidden?: boolean;
}
// =============================================================================
// Styles
// =============================================================================
const styles = stylex.create({
base: {
display: 'inline-flex',
alignItems: 'center',
gap: spacingVars['--spacing-1'],
paddingBlock: 0,
borderWidth: 0,
borderStyle: 'none',
borderRadius: radiusVars['--radius-inner'],
fontFamily: 'inherit',
fontSize: typeScaleVars['--text-supporting-size'],
lineHeight: typeScaleVars['--text-supporting-leading'],
fontWeight: fontWeightVars['--font-weight-medium'],
whiteSpace: 'nowrap',
textDecoration: 'none',
maxWidth: '100%',
overflow: 'hidden',
},
label: {
overflow: 'hidden',
textOverflow: 'ellipsis',
whiteSpace: 'nowrap',
minWidth: 0,
},
interactive: {
cursor: {
default: 'pointer',
':is(:disabled,[aria-disabled="true"])': 'default',
},
transitionProperty: 'background-image',
transitionDuration: durationVars['--duration-fast'],
transitionTimingFunction: easeVars['--ease-standard'],
},
disabled: {
cursor: 'default',
opacity: 0.5,
pointerEvents: 'none' as const,
},
labelHidden: {
position: 'absolute' as const,
width: '1px',
height: '1px',
padding: 0,
margin: '-1px',
overflow: 'hidden',
clipPath: 'inset(50%)',
whiteSpace: 'nowrap',
borderWidth: 0,
},
invisibleButton: {
cursor: {
default: 'inherit',
':is(:disabled,[aria-disabled="true"])': 'default',
},
color: 'inherit',
outline: 'none',
overflow: 'hidden',
minWidth: 0,
},
removeButton: {
display: 'inline-flex',
alignItems: 'center',
justifyContent: 'center',
position: 'relative',
padding: 0,
marginInlineEnd: `calc(-1 * ${spacingVars['--spacing-1']})`,
cursor: {
default: 'pointer',
':is(:disabled,[aria-disabled="true"])': 'default',
},
borderRadius: radiusVars['--radius-full'],
width: '16px',
height: '16px',
// A token cut by its width shrinks only its label, not the button.
flexShrink: 0,
color: 'inherit',
'::after': {
content: '""',
position: 'absolute',
inset: '-4px',
},
},
});
const sizeStyles = stylex.create({
sm: {
height: `calc(${sizeVars['--size-element-sm']} - 8px)`,
fontSize: typeScaleVars['--text-supporting-size'],
paddingInline: spacingVars['--spacing-2'],
},
md: {
height: `calc(${sizeVars['--size-element-md']} - 8px)`,
paddingInline: spacingVars['--spacing-2'],
},
lg: {
height: `calc(${sizeVars['--size-element-lg']} - 8px)`,
paddingInline: spacingVars['--spacing-2'],
},
});
const colorStyles = stylex.create({
default: {
backgroundColor: colorVars['--color-neutral'],
color: colorVars['--color-text-primary'],
},
red: {
backgroundColor: colorVars['--color-background-red'],
color: colorVars['--color-text-red'],
},
orange: {
backgroundColor: colorVars['--color-background-orange'],
color: colorVars['--color-text-orange'],
},
yellow: {
backgroundColor: colorVars['--color-background-yellow'],
color: colorVars['--color-text-yellow'],
},
green: {
backgroundColor: colorVars['--color-background-green'],
color: colorVars['--color-text-green'],
},
teal: {
backgroundColor: colorVars['--color-background-teal'],
color: colorVars['--color-text-teal'],
},
cyan: {
backgroundColor: colorVars['--color-background-cyan'],
color: colorVars['--color-text-cyan'],
},
blue: {
backgroundColor: colorVars['--color-background-blue'],
color: colorVars['--color-text-blue'],
},
purple: {
backgroundColor: colorVars['--color-background-purple'],
color: colorVars['--color-text-purple'],
},
pink: {
backgroundColor: colorVars['--color-background-pink'],
color: colorVars['--color-text-pink'],
},
gray: {
backgroundColor: colorVars['--color-background-gray'],
color: colorVars['--color-text-gray'],
},
});
// =============================================================================
// Component
// =============================================================================
/**
* A chip/tag component for displaying entities inline.
*
* Renders as a `<span>` by default, `<a>` when `href` is provided, or a
* `<span>` container with an invisible `<button>` when `onClick` is provided.
* The invisible button pattern provides real button semantics for accessibility
* while the container uses `:focus-within` to show focus outlines around the
* entire token. When both `href` and `onRemove` are provided, the same
* container pattern is used with an invisible `<a>` so the remove `<button>`
* renders as a sibling of the link rather than nested inside it.
*
* @example
* ```
* <Token label="Tag" />
* <Token label="Status" color="green" />
* <Token label="Removable" onRemove={() => {}} />
* <Token label="Clickable" onClick={() => {}} />
* <Token label="Link" href="/path" />
* ```
*/
export function Token({
label,
size = 'md',
color = 'default',
icon,
isDisabled = false,
onRemove,
onClick,
href,
description,
endContent,
isLabelHidden = false,
xstyle,
className,
style,
'data-testid': testId,
'aria-labelledby': ariaLabelledBy,
'aria-describedby': ariaDescribedBy,
'aria-haspopup': ariaHasPopup,
'aria-expanded': ariaExpanded,
ref,
...rest
}: TokenProps) {
// Constant marker props; the hook's only effect is installing the shared
// document controller once, so the token's output stays a pure function
// of its props.
const pressable = usePressFeedback();
const t = useComponentTranslator();
const LinkComponent = useLinkComponent();
const role = useInteractiveRole({href, onClick, isDisabled});
const naming = use(TokenNamingContext);
// When role is 'button' via context (no explicit onClick), treat as
// if onClick was provided — the popover attaches its own handler.
const effectiveOnClick = onClick ?? (role === 'button' ? () => {} : null);
const removeButton = onRemove != null && (
<button
type="button"
aria-label={t('@astryx.token.remove', {
label: naming?.removeName ?? label,
})}
onClick={e => {
e.stopPropagation();
onRemove(e);
}}
// Focusable while disabled (spec:AST-085 FR1), but inert (FR2).
aria-disabled={isDisabled || undefined}
{...(isDisabled ? disabledInteractionProps() : null)}
{...focusOutlineProps.focusVisible(styles.removeButton)}>
<Icon icon="close" size="xsm" color="inherit" />
</button>
);
const content = (
<>
{icon}
<span
{...stylex.props(styles.label, isLabelHidden && styles.labelHidden)}>
{label}
</span>
{endContent}
{removeButton}
</>
);
// Naming and popup inputs reach the element that owns the token's action:
// the inner button of a clickable token, otherwise the root
// (architecture:public-component-api INV5).
const labellingProps = {
'aria-labelledby': ariaLabelledBy,
'aria-describedby': ariaDescribedBy,
'aria-haspopup': ariaHasPopup,
'aria-expanded': ariaExpanded,
};
const sharedProps = {
'data-testid': testId,
...(isLabelHidden ? {'aria-label': label} : {}),
...(description != null ? {'aria-description': description} : {}),
};
// A disabled link keeps a focusable link with aria-disabled and no
// destination, as a disabled Link does (spec:AST-085 FR1, FR5;
// component:Link FR5). useInteractiveRole reports no link role once
// disabled, so the structure is chosen here.
const isDisabledLink = isDisabled && href != null && effectiveOnClick == null;
if (isDisabledLink && onRemove == null) {
// A disabled link is an <a> with no href, as Link renders one: nothing can
// navigate, it keeps a Tab stop and the link role (spec:AST-085 FR1, FR5).
// The router LinkComponent is skipped, since a custom router link may
// require a live href.
const DisabledAnchor = 'a';
return (
<DisabledAnchor
ref={ref as React.Ref<HTMLAnchorElement>}
role="link"
aria-disabled={true}
tabIndex={0}
{...mergeProps(
themeProps('token', {color, size, disabled: 'disabled'}),
focusOutlineProps.focusVisible(
styles.base,
sizeStyles[size],
colorStyles[color],
styles.interactive,
styles.disabled,
xstyle,
),
className,
style,
)}
{...rest}
{...labellingProps}
{...disabledInteractionProps(rest.onKeyDown)}
{...sharedProps}>
{content}
</DisabledAnchor>
);
}
if (role === 'link' || isDisabledLink) {
if (onRemove == null) {
return (
<LinkComponent
ref={ref as React.Ref<HTMLAnchorElement>}
href={href as string}
onClick={onClick}
{...pressable}
{...mergeProps(
themeProps('token', {
color,
size,
disabled: isDisabled ? 'disabled' : null,
}),
focusOutlineProps.focusVisible(
styles.base,
sizeStyles[size],
colorStyles[color],
styles.interactive,
interactionOverlayStyles.backgroundImage,
isDisabled && styles.disabled,
xstyle,
),
className,
style,
)}
{...rest}
{...labellingProps}
{...(isDisabled ? {'aria-disabled': true} : {})}
{...sharedProps}>
{content}
</LinkComponent>
);
}
// With a remove button, the link cannot be the root — nesting a <button>
// inside an <a> is invalid HTML (WCAG 4.1.2). Delegate to TokenLink, a
// non-presentational wrapper that renders a <span> container with the link
// and the remove button as siblings and wires up useClickableContainer so
// the whole token surface activates the link (including middle-click and
// cmd/ctrl-click to open in a new tab). Token itself stays presentational
// (no refs/effects) per the @astryx/presentational-component rule.
return (
<TokenLink
ref={ref}
href={href as string}
isDisabled={isDisabled}
onLinkClick={onClick}
LinkComponent={LinkComponent}
icon={icon}
endContent={endContent}
removeButton={removeButton}
linkStyleProps={stylex.props(styles.invisibleButton)}
{...pressable}
labelContent={
<span
{...stylex.props(
styles.label,
isLabelHidden && styles.labelHidden,
)}>
{label}
</span>
}
{...mergeProps(
themeProps('token', {
color,
size,
disabled: isDisabled ? 'disabled' : null,
}),
focusOutlineProps.focusWithin(
styles.base,
sizeStyles[size],
colorStyles[color],
styles.interactive,
interactionOverlayStyles.backgroundImage,
isDisabled && styles.disabled,
xstyle,
),
className,
style,
)}
{...rest}
{...labellingProps}
{...sharedProps}
/>
);
}
if (effectiveOnClick != null) {
const handleContainerClick = (e: React.MouseEvent) => {
const target = e.target as HTMLElement;
if (target.closest('button, a')) {
return;
}
effectiveOnClick(e);
};
// A finger press on Remove or a control in end content does not run the
// token's action, so the token shows no press for it. The inner button,
// the first button child, is the token's own action.
const handleContainerPointerDown = (
e: React.PointerEvent<HTMLSpanElement>,
) => {
rest.onPointerDown?.(e);
cancelNestedTouchPress(
e,
e.currentTarget,
e.currentTarget.querySelector(':scope > button'),
);
};
return (
<span
ref={ref}
onClick={isDisabled ? undefined : handleContainerClick}
{...pressable}
{...mergeProps(
themeProps('token', {
color,
size,
disabled: isDisabled ? 'disabled' : null,
}),
focusOutlineProps.focusWithin(
styles.base,
sizeStyles[size],
colorStyles[color],
styles.interactive,
interactionOverlayStyles.backgroundImage,
isDisabled && styles.disabled,
xstyle,
),
className,
style,
)}
{...rest}
{...sharedProps}
onPointerDown={
isDisabled ? rest.onPointerDown : handleContainerPointerDown
}>
{icon}
<button
type="button"
onClick={effectiveOnClick}
aria-label={ariaLabelledBy == null ? naming?.actionName : undefined}
{...labellingProps}
aria-disabled={isDisabled || undefined}
{...(isDisabled ? disabledInteractionProps() : null)}
{...stylex.props(styles.invisibleButton)}>
<span
{...stylex.props(
styles.label,
isLabelHidden && styles.labelHidden,
)}>
{label}
</span>
</button>
{endContent}
{removeButton}
</span>
);
}
return (
<span
ref={ref}
{...mergeProps(
themeProps('token', {
color,
size,
disabled: isDisabled ? 'disabled' : null,
}),
stylex.props(
styles.base,
sizeStyles[size],
colorStyles[color],
isDisabled && styles.disabled,
xstyle,
),
className,
style,
)}
{...rest}
{...labellingProps}
{...sharedProps}>
{content}
</span>
);
}
Token.displayName = 'Token';