Btn
test camel
Preview
Rendering the live preview…
defaultRendering the live preview…
outlinedRendering the live preview…
tonalRendering the live preview…
ghostRendering the live preview…
disabledRendering the live preview…
loadingRendering the live preview…
rounded pillStructure
Anatomy
Visual breakdown of the component's internal structure with BEM class call-outs.
<origam-btn> — 8 internal parts, each numbered per BEM class. Absolute layers (overlay ②, underlay ③, progress ④) sit over the root; the loader grid ⑤ stacks prepend / content / append in a 3-column inline-grid.- 1.origam-btn
- Root element. Renders as
<button>by default,<a>whenhrefis set. - 2.origam-btn__overlay
- Absolute scrim.
opacity: 0→ 0.12 hover → 0.2 active. Driven by--origam-btn__overlay---opacity. - 3.origam-btn__underlay
- Absolute decorative layer.
inset: 0 / pointer-events: none. Reserved for tonal/ghost compositing. - 4.origam-btn__progress
- Rendered only when
loadingis active. Modes: linear strip (loader-line) or circular spinner (loader-circular). - 5.origam-btn__loader
inline-grid, 3 columns: max-content / auto / max-content. In--stackedmode switches to 3 rows.- 6.origam-btn__prepend
- Leading slot. Renders
prependIconorprependAvatar, or the#prependslot.v-if="hasPrepend". - 7.origam-btn__content
- Label zone. Contains the
#defaultslot. Hidden viaopacity: 0inloader-circularmode. - 8.origam-btn__append
- Trailing slot. Renders
appendIconorappendAvatar, or the#appendslot.v-if="hasAppend".
API
Props
All props accepted by this component, with their type, default value and description.
- flatbooleanfalse
- Deprecated. Use variant="flat" instead. Kept for backward compatibility.
- icon
- Renders the button as an icon-only button. Pass true to shrink padding, or a TIcon string to also set the icon.
- blockbooleanfalse
- Makes the button fill the full width of its container.
- slimbooleanfalse
- Reduces horizontal padding for tighter layouts.
- stackedbooleanfalse
- Stacks the prepend icon above the label text vertically.
- wrapboolean
- textstring
- Button label text. Can also be set via the default slot.
- statusTStatus
- statusIconPositionTStatusPosition
- idstring
- classstring | Array<string> | object
- stylestring | Array<string> | object | StyleValue
- color
- Intent or custom color applied to the button surface. Accepts semantic intents (primary, success, danger…) or a CSS color. Hex values emit a deprecation warning since v0.4.
- bgColor
- Background color override, independent of the intent color.
- borderboolean | number | string | TDirectionBoth | Array<TDirectionBoth>false
- Applies a border. Pass true for the default border or a CSS shorthand.
- borderTopboolean | number | string
- Per-side top border override (width, or a full "width style color" string). Wins over the global border/borderColor/borderStyle for the top side.
- borderLeftboolean | number | string
- Per-side left border override (width, or a full "width style color" string). Wins over the global border/borderColor/borderStyle for the left side.
- borderBottomboolean | number | string
- Per-side bottom border override (width, or a full "width style color" string). Wins over the global border/borderColor/borderStyle for the bottom side.
- borderRightboolean | number | string
- Per-side right border override (width, or a full "width style color" string). Wins over the global border/borderColor/borderStyle for the right side.
- readonlybooleanfalse
- Makes the button non-interactive without disabling it visually.
- borderBlockboolean | number | string
- borderInlineboolean | number | string
- borderInlineStartboolean | number | string
- borderInlineEndboolean | number | string
- targetstring
- Anchor target attribute, e.g. "_blank".
- relstring
- Anchor rel attribute, e.g. "noopener noreferrer".
- borderBlockStartboolean | number | string
- borderBlockEndboolean | number | string
- borderColorstring
- Override border color without affecting width or style.
- borderStylestring
- Override border style (solid, dashed, dotted…).
- borderTopColor
- Per-side top border colour override. Wins over borderTop's embedded colour and the global borderColor.
- borderRightColor
- Per-side right border colour override. Wins over borderRight's embedded colour and the global borderColor.
- borderBottomColor
- Per-side bottom border colour override. Wins over borderBottom's embedded colour and the global borderColor.
- borderLeftColor
- Per-side left border colour override. Wins over borderLeft's embedded colour and the global borderColor.
- borderInlineStartColorTColor
- borderInlineEndColorTColor
- borderBlockStartColorTColor
- borderBlockEndColorTColor
- Adjusts vertical and horizontal padding density.
- heightnumber | string
- Overrides the button height. Accepts a CSS length or a number (converted to px).
- maxHeightnumber | string
- maxWidthnumber | string
- Maximum button width.
- minHeightnumber | string
- minWidthnumber | string
- Minimum button width.
- widthnumber | string
- Overrides the button width.
- elevationTElevation
- Box-shadow elevation token. Overrides the variant default elevation.
- Border-radius token or boolean. true = theme default; pill = full-round.
- roundedTopRightboolean | number | string
- roundedTopLeftboolean | number | string
- roundedBottomLeftboolean | number | string
- roundedBottomRightboolean | number | string
- roundedStartStartboolean | number | string
- roundedStartEndboolean | number | string
- roundedEndStartboolean | number | string
- roundedEndEndboolean | number | string
- tagstring'button'
- HTML element rendered at the root. Defaults to button; becomes a when href or to is set.
- Controls the button height and font-size via design tokens.
- hrefstring
- Renders the button as an anchor tag pointing to this URL.
- replaceboolean
- Vue Router destination. Automatically sets tag="a" and uses router-link.
- exactboolean
- rippleboolean | { class: string }true
- Enables the Material ripple effect on click. Set to false to disable.
- Shows a progress spinner and sets aria-busy while true.
- loadingTextstring
- positionTPosition
- topnumber | string
- bottomnumber | string
- leftnumber | string
- rightnumber | string
- locationTAnchor
- valueany
- disabledbooleanfalse
- Disables the button. Sets aria-disabled and prevents click events.
- selectedClassstring
- paddingboolean | number | string
- paddingTopboolean | number | string
- paddingLeftboolean | number | string
- paddingBottomboolean | number | string
- paddingRightboolean | number | string
- paddingBlockboolean | number | string
- paddingInlineboolean | number | string
- paddingInlineStartboolean | number | string
- paddingInlineEndboolean | number | string
- paddingBlockStartboolean | number | string
- paddingBlockEndboolean | number | string
- marginboolean | number | string
- marginTopboolean | number | string
- marginLeftboolean | number | string
- marginBottomboolean | number | string
- marginRightboolean | number | string
- marginBlockboolean | number | string
- marginInlineboolean | number | string
- marginInlineStartboolean | number | string
- marginInlineEndboolean | number | string
- marginBlockStartboolean | number | string
- marginBlockEndboolean | number | string
- appendAvatarstring
- Image URL for an avatar displayed in the append slot.
- appendIcon
- MDI or custom icon displayed after the label.
- prependAvatarstring
- Image URL for an avatar displayed in the prepend slot.
- prependIcon
- MDI or custom icon displayed before the label.
- prependAriaLabelstring
- appendAriaLabelstring
- hoverboolean | IStateEffectConfig
- hoverClassstring
- activeboolean | IStateEffectConfigfalse
- Forces the button into its active/pressed visual state.
- activeClassstring
- Visual style variant. Controls elevation, fill and border rendering.
- fontSizeTFontSize
- fontWeightTFontWeight
- lineHeightTLineHeight
- letterSpacingTLetterSpacing
API
Slots
Content slots exposed by this component.
- #wrapper
- Replaces the entire inner layout (advanced). Use when you need full control over prepend/content/append.
- #loader
- Custom spinner shown while loading=true. progressProps mirrors OrigamProgress props.
- #default
- Main button label content. Overrides the text prop.
- #prepend
- Replaces the prepend icon/avatar area with custom content.
- #append
- Replaces the append icon/avatar area with custom content.
API
Emits
Events emitted by this component.
- @group:selected{ value: boolean }
- @clickMouseEvent
- Fired on button click. Also fires on Enter/Space for keyboard users.
- @update:hoverboolean
- @click:prependMouseEvent
- Fired when the user clicks the prepend slot area. Stops propagation.
- @click:appendMouseEvent
- Fired when the user clicks the append slot area.
API
Exposed members
Properties and methods accessible via template ref (defineExpose). Use them for programmatic control.
- GroupItemProvide | null
- Group item context when the button is inside a BtnToggle or BtnGroup. Null otherwise.
- <T extends object>(props: T, exclude?: string[]) => Partial<T>
- Utility to forward a filtered subset of props to a child component (e.g. OrigamProgress inside the loader slot).
- Ref<string>
- Reactive CSS string generated by useStyle from the computed btnStyles. Used by OrigamDefaultsProvider to inject styles.
- string
- Unique style-sheet ID for this instance (used by useStyle to scope injected CSS).
- () => void
- Injects the computed style sheet into the document. Called automatically on mount.
- () => void
- Removes the injected style sheet. Called automatically on unmount.
- Ref<boolean>
- True once the style sheet has been injected into the DOM.
Customisation
CSS variables
CSS custom properties exposed by this component. Override them to customise the component without losing theme compatibility.
- Default button background color. Resolves to the secondary action surface.
- Default foreground (text/icon) color.
- Button height. Overridden per size class (x-small: 20px … x-large: 52px).
- Button font size. Overridden per size variant.
- Button font weight.
- Letter spacing applied to button label.
- Border radius. Overridden by rounded prop and icon mode.
- Border radius when icon=true (full circle).
- Button opacity. Set to --origam-btn---opacity-disabled (0.5) when disabled.
- Box shadow used by variant="elevated".
- Transition duration for shadow, transform, opacity and background.
- Density offset applied to height and min-width. compact: -8px, comfortable: +8px.
- Overlay opacity. Animates on hover (0.12) and active (0.2).
Inclusion
Accessibility
ARIA roles, keyboard navigation and focus management. Sourced from the real component template.
ARIA roles
Keyboard interactions
| Key | Action |
|---|---|
| Enter / Space | Activates the button (fires click event). Native <button> behavior. |
| Tab | Moves focus to the next interactive element. |
Notes
- When disabled=true and tag is <a>, aria-disabled="true" is set instead of the disabled attribute (which has no effect on anchors). Pointer events are removed via CSS.
- Focus-visible outline uses 2px solid currentColor with a 2px offset. The outline is only shown for keyboard navigation (not mouse click).
- When loading=true, OrigamProgress is injected with role="progressbar". The button is non-interactive (pointer-events: none) during loading.
- All transitions are disabled under prefers-reduced-motion: reduce.
- Icon-only buttons (icon prop) must have an aria-label describing the action — the label text is not visible.
Foundation
Design tokens
Excerpt from this component's token declarations — the --origam-<component>---<property> variables, declared in its hand-maintained token sheet with no build step.
- color{color.action.secondary.bg}
- Default button background. References the semantic secondary action background.
- color{color.action.secondary.fg}
- Default foreground color (text and icons).
- dimension{radius.sm}
- Default border radius. Overridden to {radius.full} for icon-only buttons.
- dimension36px
- Default height. Size variants override this (height-xs=20px … height-xl=52px).
- fontWeight{font.weight.medium}
- Label font weight.
- duration{motion.duration.slow}
- Duration of shadow, transform, opacity and background transitions.
- shadow{shadow.md}
- Box shadow for variant="elevated".
- color{color.action.primary.bg}
- Background when color="primary".
Interactive
Playground
Edit props live and see the component update in real time. The generated code snippet updates as you change values.
Rendering the live preview…
Usage
Examples
Ready-to-paste code snippets for your templates.
Variants
Intents (color)
Icons & states
Updated title
Ecosystem
Family
Components from the same folder that share conventions and often compose together.