Tag

A small tag used for marking and categorization.

Types

Tag types

DefaultPrimarySuccessWarningDangerInfo

Example

Radius & size

Radius & size

PillXSSmallMediumLargeXL

Example

size supports five tiers: xs / small / medium (default) / large / xl; invalid values fall back to medium with a warning.

Closable

Clicking × dispatches oas-close (cancelable; preventDefault can prevent removal).

Closable tags

ClosableClick × to closeRemoved after close

Example

Custom close

close-icon customizes the close button icon (an oas-icon icon-set name, default ×); close-label customizes the close button's aria-label (screen-reader announcement, defaulting to the locale "Close").

Custom close icon & label

Trash closeMinus closeCustom label

Example

Chip & clickable

chip: pill radius + compact padding; clickable: the whole tag is clickable, dispatching oas-click on click/Enter/Space.

Chip

Default chipPrimary chipSuccess chipWarning chipClosable chip

Example

Clickable

Click me to dispatch oas-clickClickable chipRegular clickable tagDisabled, not clickable

Example

In chip mode, disabled tags cannot be clicked (no oas-click) nor closed (close button disabled).

Icon tags

The default slot can hold an icon — combining an icon and text forms an icon tag.

Icon tags

FeaturedCompletedFollowScheduled

Example

Selectable

checkable enables selection: click / Enter / Space toggles checked and dispatches oas-change (detail: { checked }); the selected state is a solid fill with a √ check icon before the text (checked-icon can customize the icon name). checkable is mutually exclusive with closable (the close button is hidden).

checkable tags

DefaultSuccessChipDisabled, not selectable

Example

checkable check icons

Selected (√)Star checkCircle-check chip

Example

Variants

variant provides three shapes: outlined / filled / solid; when unset, the legacy type rendering is kept (default white bg with gray border, colored types soft fill, primary solid).

Outlined

DefaultPrimarySuccessDanger

Example

Filled

DefaultPrimarySuccessWarning

Example

Solid

DefaultPrimarySuccessWarningDanger

Example

Custom color

color accepts any CSS color value and overrides the type semantic color; it renders as filled when variant is unset.

color custom

PurpleSky outlinedRose solidGreen filled

Example

Icon

The icon attribute reuses the oas-icon icon set; the icon renders before the text, sized to the font.

Icon tags

FeaturedCompletedScheduledMail

Example

Trailing icon

icon-end is the mirror of icon: it renders at the tail of the text (before the close button), reuses the oas-icon icon set, is sized to the font, and can coexist with a leading icon on the same tag.

icon-end trailing icon

Go to detailsLimited-time dealExternal linkMail (closable)

Example

Link

When href is set, the tag renders a native <a> internally; target is passed through.

href link tags

Open in new tabOutlined link

Example

Max width ellipsis

max-width limits the tag content width; overflow is truncated with an ellipsis.

max-width ellipsis

This is a very long tag label that will be truncated with an ellipsis when it exceeds the maximum widthShort

Example

Preset colors

color accepts 11 preset names (magenta / red / volcano / orange / gold / lime / green / cyan / blue / geekblue / purple, mapped to --oas-preset-* tokens, auto-brightened in dark theme); any CSS color value also works (see Custom color above). Unknown preset names are treated as plain color values.

Preset colors filled

magentaredvolcanoorangegoldlimegreencyanbluegeekbluepurple

Example

Preset colors solid

magentaredvolcanoorangegoldlimegreencyanbluegeekbluepurple

Example

Status dot

dot renders a small dot before the text (color follows type / color); processing adds a pulsing animation (disabled under prefers-reduced-motion) and implies dot.

dot status dots

DefaultPublishedReviewingCustom color dot

Example

processing pulse

ProcessingWaitingPolling

Example

Hit & emphasis

hit draws an opaque semantic-color border (follows the custom color when set); strong makes the text bold (font-weight 600).

hit bordered

DefaultPrimary borderCustom color borderOutlined hit

Example

strong

ImportantBold chip

Example

Multiline

multiline allows content to wrap (auto height + vertical padding compensation, for long content on mobile); when combined with max-width, the width constraint still applies — content wraps instead of being truncated.

multiline

This is a long tag label that wraps naturally in a narrow container on mobile instead of being truncatedA second multiline label showing the auto-height layout with vertical padding compensation

Example

Avatar tags

When the default slot holds an oas-avatar (or <img>), it is adapted automatically: sized to the tag tier, circular, with a negative margin to hug the left edge.

Avatar tags

JJimAAnnaMMikeZZoe

Example

Drag to reorder

A set of closable tags supports native HTML5 drag & drop reordering (dragstart / dragover / drop, re-rendered from the reordered array; no third-party dependency).

Drag to reorder

Example

Close animation

oas-close is a cancelable event: after preventDefault the tag is not removed automatically, so you can fade it out first and then remove it.

Close animation

Fade out & removeClick × to animateAnimated close

Example

Async close

loading enters the closing-loading state: the close button shows a spinner and is disabled (aria-busy synced). Inside oas-close, preventDefault stops the auto-removal, the host runs the async task, then calls event.detail.done() to exit loading before removing the tag.

Async close

Click × to simulate async confirmRemoved after async

Example

Tag group

oas-tag-group groups several checkable tags into a value selector: single-select (value as a single value) and multi-select (multiple + comma-separated value). Clicking a tag toggles selection and dispatches oas-change (single: detail: { value } / multiple: detail: { value: [] }); disabled disables the whole group. Child checked states are managed by the group (controlled).

tag-group single

Option AOption BOption C

Example

tag-group multiple

Tag ATag BTag C

Example

tag-group disabled

Disabled ADisabled BDisabled C

Example

Touch targets on mobile

On touch devices (pointer: coarse) interactive hit areas grow automatically; desktop (fine pointer) is completely unaffected:

• The closable × hit area expands to 44px (--oas-touch-target-min) while the visible × icon stays the same size;
• clickable / checkable tags get a 44px minimum height (including multiline); non-interactive tags keep their original size.

Try it with DevTools device emulation (e.g. iPhone SE 375×667); desktop browsers see no change.

API

oas-tag

Attributes

Attribute	Description	Type	Default
checkable	Selectable: click / Enter / Space toggles checked and dispatches oas-change; mutually exclusive with closable	boolean	—
checked	Checked state (effective when checkable)	boolean	—
checked-icon	Checkmark icon before a checked checkable tag (built-in icon name, default check)	string	check
chip	Chip (pill radius + compact padding)	boolean	—
clickable	Whole tag clickable (focusable, dispatches oas-click)	boolean	—
closable	Closable	boolean	—
close-icon	Custom close-button icon (built-in icon name), replaces the default ×	string	—
close-label	aria-label of the close button (a11y context, e.g. "Remove tag xx"); defaults to the locale "Close"	string	—
color	Custom color: 11 preset names (magenta / red / volcano / orange / gold / lime / green / cyan / blue / geekblue / purple, mapped to --oas-preset-* tokens) or any CSS value, overrides the type semantic color; renders as filled when variant is unset	string	—
disabled	Disabled (cannot be clicked or closed)	boolean	—
dot	Status dot before the text (8px, color follows type / color)	boolean	—
hit	Heavy border: opaque semantic-color outline (follows the custom color when set)	boolean	—
href	Link URL: renders a native <a> when set	string	—
icon	Icon name (reusing the oas-icon icon set), placed before the text, sized to the font	string	—
icon-end	Icon-set name (oas-icon icon name) rendered at the tail of the text (before the close button), sized to the font; can coexist with icon	string	—
loading	Loading state: spinner replaces the close icon and blocks clicks (oas-close detail has a done() callback the host calls after async work)	boolean	—
max-width	Max width of the tag content (e.g. 120px); overflow is truncated with an ellipsis; with multiline it only constrains the width so content wraps	string	—
multiline	Multiline: content wraps (auto height + vertical padding compensation); with max-width content wraps instead of being truncated	boolean	—
processing	Pulsing status dot (implies dot); disabled under prefers-reduced-motion	boolean	—
round	Rounded	boolean	—
size	Size: xs / small / medium (default) / large / xl; invalid values fall back to medium with a warning	TagSize	medium
strong	Bold text (font-weight 600)	boolean	—
target	How the link opens (_blank / _self etc.), with href	string	—
type	Type	TagType	default
variant	Shape (orthogonal to type): outlined / filled / solid; when unset, keeps the legacy type rendering	string	—

Events

Event	Description
oas-change	Selection toggled when checkable, detail: { checked }
oas-click	Whole-tag click (when clickable), detail contains originalEvent
oas-close	Close, cancelable; preventDefault prevents removal

Slots

Name	Description
default	Tag content

CSS Variables

CSS Variable	Description	Default
--oas-tag-avatar-size	Avatar size for avatar mode, derived per size level and falling back to control-height-sm − 4px when no level matches	calc(var(--oas-control-height-sm) - 4px)
--oas-tag-color	Text color: the color attribute feeds through this variable; --tag-color is the component's internal current color, falling back to text-primary when unset	var(--tag-color, var(--oas-color-text-primary))
--oas-tag-color-deep	Text-safe color (deep level): drives both the text color of filled/outlined and the solid background of solid/checked, falling back to text-primary when unset	var(--tag-color-deep, var(--oas-color-text-primary))

oas-tag-group

Attributes

Attribute	Description	Type	Default
aria-label	Accessible name of the group container (defaults to i18n "Tag group")	—	—
disabled	Disables the whole group (children cannot toggle)	boolean	—
multiple	Multi-select mode (value holds comma-separated selected values)	boolean	—
value	Selected value: a single value for single-select, comma-separated for multi-select	string	—

Events

Event	Description
oas-change	Selection change. Single: detail: { value }; multiple: detail: { value: [] }

Slots

Name	Description
default	Multiple <oas-tag checkable value="x"> children

Tag group API table is generated by the generator.