Button

Basic button component, an enhanced native <button>.

Types

Button types

DefaultPrimarySuccessWarningDangerText

Example

Sizes

Five sizes

XSSmallMediumLargeXL

Example

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

Five sizes · primary

XSSmallMediumLargeXL

Example

Five sizes · icon-only

Example

Disabled & Loading

disabled disables the button; loading enters the loading state — the original label keeps its space (width stays unchanged) and a spinner is centered; pair with loading-text to show a loading message.

Disabled and loading states

DisabledLoadSubmit

Example

Async auto loading

With loading="auto", the button automatically enters the loading state while the host oas-click handler returns a Promise, and exits after the Promise resolves or rejects.

Auto loading for async submit

Click to submitSave async

Example

Disabled but focusable

disabled-focusable renders a disabled look (desaturated + aria-disabled) without a native disabled attribute — still focusable and hoverable, ideal for wrapping in a tooltip that explains why it is disabled; clicks are intercepted by the component and oas-click is not dispatched.

Disabled but focusable (with tooltip)

Sign in to continueDownload report

Example

Events

Click event

Click me

Example

Clicking dispatches the oas-click CustomEvent (bubbles + composed); detail.originalEvent is the native MouseEvent.

Icon buttons

icon renders an icon before the text (reusing the oas-icon icon set, IconName); the spacing between the icon and text follows --oas-space-2.

Icon + text

SearchDownloadDeleteNew

Example

Without text, the button becomes an equal-width square and needs an aria-label for an accessible name; when not set explicitly, the icon name is used as a fallback (e.g. icon="close" → aria-label="close"). It is recommended to provide an explicit label.

Icon-only buttons

Example

Block

block makes the button fill the full width of its parent container.

Block buttons

Block buttonDownload

Example

Rounded

round applies a pill radius (--oas-radius-full, falling back to 999px when the token is unavailable).

Rounded buttons

DoneUnsubscribe

Example

Ghost

ghost renders a transparent background with an outline; the outline and text are colored by type and darken on hover.

Ghost buttons

Default ghostPrimary ghostSuccess ghostWarning ghostDanger ghost

Example

Circle

circle turns the button into a circle; icon-only buttons combine equal-width and full rounding into a circle.

Circle buttons

Example

Icon position

icon-position controls the icon/text order: start (default, icon on the left) or end (icon on the right).

Icon on the right

DownloadNext

Example

Dual icons

icon renders an icon before the text and icon-end renders a second icon after the text (both reuse the oas-icon set); they can coexist with icon-position.

Dual icons

Download & continueNextConfirm & submit

Example

Link button

Setting href renders a native link (<a>); target controls how it opens (_blank / _self etc.); download (file download) and rel (link relationship) are passed through.

Link buttons

Default linkOpen in new tab

Example

Download and rel

Download quarterly reportExternal link (rel=noopener)

Example

Plain

plain uses a low-contrast, subtle style (transparent background with softened outline and text), gentler on light backgrounds.

Plain buttons

Plain buttonPrimary plainDanger plain

Example

Variant

variant controls the button shape, orthogonal to the type semantic color: solid (default filled) / outlined / dashed / filled (soft) / text / link. Legacy ghost equals outlined, plain equals filled.

Outlined / Dashed / Filled

OutlinedDashedFilledDefault outlinedDefault dashed

Example

Text / Link

Text buttonPrimary textLink button

Example

Custom color

color overrides the type semantic color with any color value.

Color priority: --oas-button-bg (host-injected CSS variable, gradients allowed) > color attribute > type semantic color > default gray. In outlined / filled / dashed / text variants, color tints the border/text/light background; for solid buttons the text color is picked black or white by background luminance (stays readable in dark mode).

Custom color values are rendered as-is (never rewritten) — make sure the text/background contrast meets WCAG AA (4.5:1).

Custom color

Purple solidGreen outlinedPink filled

Example

Press feedback

wave enables a subtle press feedback (slight sink + darken, on by default); wave="false" disables it.

Press feedback

Press me (on by default)Feedback off

Example

CJK auto spacing

auto-insert-space inserts a space between two consecutive CJK characters (typography optimization, off by default).

CJK auto spacing

保存设置确认提交订单

Example

Autofocus

autofocus gives the button focus after page load (native autofocus does not pierce Shadow DOM; the component forwards focus to the inner button on mount).

autofocus

Focused on loadNormal button

Example

Long content wrapping

Buttons are single-line by default (white-space: nowrap). With the explicit wrap attribute, long text wraps within a constrained width (parent container or width / max-width) and the box grows with the content (same height as default when it fits on one line).

wrap for long content

A long button label that wraps automaticallyLong primary button text wraps in a narrow container

Example

API

Attributes

Attribute	Description	Type	Default
auto-insert-space	CJK auto spacing: inserts a space between two consecutive CJK characters (off by default)	string	—
autofocus	Autofocus: focuses the inner button on mount (native autofocus does not pierce Shadow DOM; the component forwards it)	boolean	—
block	Fill the full width of the parent container (block level)	boolean	—
circle	Circle button (icon-only, square + full rounding)	boolean	—
color	Custom color: overrides the type semantic color (any color value)	string	—
disabled	Disabled	boolean	—
disabled-focusable	Visually disabled but stays focusable/hoverable (aria-disabled + click intercepted), for tooltips explaining why	boolean	—
download	Passthrough download attribute in link mode (href) for file-download buttons	string	—
ghost	Ghost/outline style: transparent background + outline colored by type, darkens on hover	boolean	—
href	Link address: renders a native <a> when set	string	—
icon	Icon name (reusing the oas-icon icon set); without text it becomes an equal-width square and uses the icon name as the fallback label	string	—
icon-end	A second icon after the text (iconRegistry name), works with icon/icon-position — e.g. left icon + right dropdown arrow	string	—
icon-position	Icon position: start (default, left) / end (right)	string	start
loading	Loading state	—	—
loading-text	Text shown while loading (e.g. "Submitting…"); replaces the label content when set	string	—
plain	Plain style: low-contrast soft (transparent bg + softened text), equals variant="filled"	boolean	—
rel	Passthrough rel attribute in link mode (pair noopener with target="_blank")	string	—
round	Pill radius (--oas-radius-full / 999px)	boolean	—
size	Size: xs / small / medium (default) / large / xl; invalid values fall back to medium with a warning	ButtonSize	medium
target	How the link opens (_blank / _self etc.), with href	string	—
type	Type	ButtonType	default
variant	Shape (orthogonal to type): solid (default filled) / outlined / dashed / filled (soft) / text / link	ButtonVariant | ''	—
wave	Press feedback: slight sink + darken (on by default); wave="false" disables	string	true
wrap	Long-text wrapping: single-line nowrap by default; when enabled, content wraps within constrained widths and the box grows with it	boolean	—

Events

Event	Description
oas-click	Click, detail: { originalEvent }

Slots

Name	Description
default	—