Btn

Form & Input
stable

test camel

Preview

Rendering the live preview…

default

Rendering the live preview…

outlined

Rendering the live preview…

tonal

Rendering the live preview…

ghost

Rendering the live preview…

disabled

Rendering the live preview…

loading

Rendering the live preview…

rounded pill

Structure

Anatomy

Visual breakdown of the component's internal structure with BEM class call-outs.

Anatomy of OrigamBtnSchematic of the Btn component with 8 numbered internal parts. icon Label / #default slot icon 1 2 abs · opacity 0 3 abs · décoratif 4 loader-line | loader-circular 5 6 7 8 origam-btn __loader · inline-grid 3col ② ③ ④ = calques absolus, invisibles au repos ou conditionnels
Anatomy of <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> when href is 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 loading is 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 --stacked mode switches to 3 rows.
6.origam-btn__prepend
Leading slot. Renders prependIcon or prependAvatar, or the #prepend slot. v-if="hasPrepend".
7.origam-btn__content
Label zone. Contains the #default slot. Hidden via opacity: 0 in loader-circular mode.
8.origam-btn__append
Trailing slot. Renders appendIcon or appendAvatar, or the #append slot. v-if="hasAppend".

API

Props

All props accepted by this component, with their type, default value and description.

flat
boolean
false
Deprecated. Use variant="flat" instead. Kept for backward compatibility.
Renders the button as an icon-only button. Pass true to shrink padding, or a TIcon string to also set the icon.
block
boolean
false
Makes the button fill the full width of its container.
slim
boolean
false
Reduces horizontal padding for tighter layouts.
stacked
boolean
false
Stacks the prepend icon above the label text vertically.
wrap
boolean
text
string
Button label text. Can also be set via the default slot.
status
TStatus
statusIconPosition
TStatusPosition
id
string
class
string | Array<string> | object
style
string | 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.
border
boolean | number | string | TDirectionBoth | Array<TDirectionBoth>
false
Applies a border. Pass true for the default border or a CSS shorthand.
borderTop
boolean | 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.
borderLeft
boolean | 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.
borderBottom
boolean | 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.
borderRight
boolean | 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.
readonly
boolean
false
Makes the button non-interactive without disabling it visually.
borderBlock
boolean | number | string
borderInline
boolean | number | string
borderInlineStart
boolean | number | string
borderInlineEnd
boolean | number | string
target
string
Anchor target attribute, e.g. "_blank".
rel
string
Anchor rel attribute, e.g. "noopener noreferrer".
borderBlockStart
boolean | number | string
borderBlockEnd
boolean | number | string
borderColor
string
Override border color without affecting width or style.
borderStyle
string
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.
borderInlineStartColor
TColor
borderInlineEndColor
TColor
borderBlockStartColor
TColor
borderBlockEndColor
TColor
density
'default'
Adjusts vertical and horizontal padding density.
height
number | string
Overrides the button height. Accepts a CSS length or a number (converted to px).
maxHeight
number | string
maxWidth
number | string
Maximum button width.
minHeight
number | string
minWidth
number | string
Minimum button width.
width
number | string
Overrides the button width.
elevation
TElevation
Box-shadow elevation token. Overrides the variant default elevation.
Border-radius token or boolean. true = theme default; pill = full-round.
roundedTopRight
boolean | number | string
roundedTopLeft
boolean | number | string
roundedBottomLeft
boolean | number | string
roundedBottomRight
boolean | number | string
roundedStartStart
boolean | number | string
roundedStartEnd
boolean | number | string
roundedEndStart
boolean | number | string
roundedEndEnd
boolean | number | string
tag
string
'button'
HTML element rendered at the root. Defaults to button; becomes a when href or to is set.
size
'default'
Controls the button height and font-size via design tokens.
href
string
Renders the button as an anchor tag pointing to this URL.
replace
boolean
Vue Router destination. Automatically sets tag="a" and uses router-link.
exact
boolean
ripple
boolean | { 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.
loadingText
string
position
TPosition
top
number | string
bottom
number | string
left
number | string
right
number | string
location
TAnchor
value
any
disabled
boolean
false
Disables the button. Sets aria-disabled and prevents click events.
selectedClass
string
padding
boolean | number | string
paddingTop
boolean | number | string
paddingLeft
boolean | number | string
paddingBottom
boolean | number | string
paddingRight
boolean | number | string
paddingBlock
boolean | number | string
paddingInline
boolean | number | string
paddingInlineStart
boolean | number | string
paddingInlineEnd
boolean | number | string
paddingBlockStart
boolean | number | string
paddingBlockEnd
boolean | number | string
margin
boolean | number | string
marginTop
boolean | number | string
marginLeft
boolean | number | string
marginBottom
boolean | number | string
marginRight
boolean | number | string
marginBlock
boolean | number | string
marginInline
boolean | number | string
marginInlineStart
boolean | number | string
marginInlineEnd
boolean | number | string
marginBlockStart
boolean | number | string
marginBlockEnd
boolean | number | string
appendAvatar
string
Image URL for an avatar displayed in the append slot.
appendIcon
MDI or custom icon displayed after the label.
prependAvatar
string
Image URL for an avatar displayed in the prepend slot.
prependIcon
MDI or custom icon displayed before the label.
prependAriaLabel
string
appendAriaLabel
string
hover
boolean | IStateEffectConfig
hoverClass
string
active
boolean | IStateEffectConfig
false
Forces the button into its active/pressed visual state.
activeClass
string
variant
'elevated'
Visual style variant. Controls elevation, fill and border rendering.
fontSize
TFontSize
fontWeight
TFontWeight
lineHeight
TLineHeight
letterSpacing
TLetterSpacing

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 }
@click
MouseEvent
Fired on button click. Also fires on Enter/Space for keyboard users.
@update:hover
boolean
@click:prepend
MouseEvent
Fired when the user clicks the prepend slot area. Stops propagation.
@click:append
MouseEvent
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

button

Keyboard interactions

Keyboard interactions
KeyAction
Enter / SpaceActivates the button (fires click event). Native <button> behavior.
TabMoves 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.

Source
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.
dimension
36px
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

vue

Intents (color)

vue

Icons & states

vue

Updated title

vue

Ecosystem

Family

Components from the same folder that share conventions and often compose together.