Appearance
OrigamBtn
<OrigamBtn> is the polymorphic action element for origam. It renders a <button>, an <a>, or any other tag (tag prop) and exposes the full intent / variant / size / density mixin set.
Basic usage
vue
<template>
<OrigamBtn text="Click me" />
</template>Variants
vue
<template>
<div class="demo-row">
<OrigamBtn variant="flat" text="Flat" />
<OrigamBtn variant="elevated" text="Elevated" />
<OrigamBtn variant="tonal" text="Tonal" />
<OrigamBtn variant="outlined" text="Outlined" />
<OrigamBtn variant="text" text="Text" />
<OrigamBtn variant="plain" text="Plain" />
</div>
</template>Color (intent)
Origam v2 only accepts semantic intent values for color (raw hex still works but emits a deprecation warning — full removal in v3.0.0).
vue
<template>
<div class="demo-row">
<OrigamBtn color="primary" text="Primary" />
<OrigamBtn color="secondary" text="Secondary" />
<OrigamBtn color="ghost" text="Ghost" />
<OrigamBtn color="success" text="Success" />
<OrigamBtn color="danger" text="Danger" />
<OrigamBtn color="warning" text="Warning" />
<OrigamBtn color="info" text="Info" />
</div>
</template>For one-off custom colors, use a :style binding instead of color:
vue
<OrigamBtn :style="{ '--origam-btn---background-color': '#7c3aed' }" text="Custom" />Sizes
vue
<template>
<div class="demo-row">
<OrigamBtn size="x-small" text="X-Small" />
<OrigamBtn size="small" text="Small" />
<OrigamBtn size="default" text="Default" />
<OrigamBtn size="large" text="Large" />
<OrigamBtn size="x-large" text="X-Large" />
</div>
</template>Density
vue
<template>
<div class="demo-row">
<OrigamBtn density="compact" text="Compact" />
<OrigamBtn density="default" text="Default" />
<OrigamBtn density="comfortable" text="Comfortable" />
</div>
</template>Icons (prepend / append)
vue
<template>
<OrigamBtn prepend-icon="mdi-account" text="Profile" />
<OrigamBtn append-icon="mdi-arrow-right" text="Next" />
<OrigamBtn icon="mdi-heart" /> <!-- icon-only -->
</template>States
vue
<template>
<OrigamBtn disabled text="Disabled" />
<OrigamBtn loading text="Loading…" />
<OrigamBtn readonly text="Readonly" />
<OrigamBtn active text="Active" />
</template>Loading (an action in flight)
loading is true, a number (0..100, determinate), or { type: 'circular' | 'line', … }. The label stays rendered (the accessible name is unchanged and the width does not move); an indicator is laid over it. The button is aria-busy="true" andaria-disabled="true" - never the native disabled, so it keeps focus - and ignores clicks (pointer, Enter and Space alike) until the action ends.
{ type: 'skeleton' } is refused at compile time (TControlLoadingValue): a button that is mid-action is not a placeholder. Use OrigamSkeleton for content that does not exist yet.
vue
<template>
<OrigamBtn :loading="saving" text="Save" />
<OrigamBtn :loading="{ type: 'line' }" text="Save" />
</template>Modifiers
vue
<template>
<OrigamBtn block text="Full-width" />
<OrigamBtn slim text="Tight padding" />
<!-- Stacked: icon above the label -->
<OrigamBtn stacked prepend-icon="mdi-heart" text="Stacked" />
<!-- Wrap: a long label goes onto several lines instead of overflowing -->
<OrigamBtn block wrap text="Enregistrer et continuer vers la page de confirmation" />
<!-- Rounded radius variants -->
<OrigamBtn rounded text="Rounded" />
</template>block inside a flex parent
block makes the button take 100% of its parent's width (width: 100%, flex: 0 0 auto). It does not grow along the main axis: in a flex-direction: column parent (for instance a card stretched to the height of its neighbour) the button keeps its own height.
A row of several block buttons no longer shares the space by flex-grow: each one is 100% wide. Use OrigamBtnGroup or a CSS grid for that layout. max-width does not cap a block button (min-width: 100% wins), which is unchanged.
Border customization
The outlined and ghost variants expose a customizable border. Beyond the border shorthand (inherited from IBorderProps), the standalone borderColor and borderStyle props override only the colour or the line-style without restating the width — the width stays theme-driven.
vue
<template>
<OrigamBtn variant="outlined" border-color="tomato" text="Custom color" />
<OrigamBtn variant="outlined" border-style="dashed" text="Dashed" />
<OrigamBtn variant="outlined" border-color="rebeccapurple" border-style="dotted" text="Both" />
</template>The outlined variant resolves its colour from var(--origam-btn---border-color, currentColor), so per-instance overrides work via the prop, a token, or an inline --origam-btn---border-color.
Width. The outline is a real border, and the outlined and ghost variants subtract its width from padding-inline through the internal token --origam-btn---border-compensation (0px by default, set by the variant to --origam-btn---border-width-outlined / --origam-btn---border-width-ghost). A bordered button therefore has exactly the outer width of a flat button of the same size and text, whatever the width of the outline. Before this change the outer width grew by twice the outline width (breaking change: existing outlined and ghost buttons are narrower by that amount). The border prop on other variants does not compensate.
border on the default (non-outlined) variant
The border shorthand also works standalone, without variant="outlined" — true (or the 'thin' / 'thick' utility keywords) paints all four sides; 'top' / 'right' / 'bottom' / 'left' paints a single edge only:
vue
<template>
<OrigamBtn border text="All sides (1px)" />
<OrigamBtn border="thin" text="Thin (1px)" />
<OrigamBtn border="thick" text="Thick (2px)" />
<OrigamBtn border="none" text="Explicit opt-out (0)" />
<OrigamBtn border="top" text="Top only" />
<OrigamBtn border="bottom" text="Bottom only" />
<OrigamBtn :border="4" text="Numeric (4px)" />
<OrigamBtn border="2px dashed" text="Free-form string" />
</template>Measured widths (Chromium, default theme):
| value | rendered |
|---|---|
| (prop absent) | 0px |
border="none" | 0px |
border (boolean) | 1px |
border="thin" | 1px |
border="thick" | 2px |
border="top" | 1px top, 0 elsewhere |
:border="4" | 4px |
border="2px dashed" | 2px dashed |
Width is resolved per physical side (--origam-btn---border-{top,right,bottom,left}-width, each falling back to the general --origam-btn---border-width token), so a direction only ever paints the side it names — the other three stay at 0.
Why the width keywords are emitted inline (#391)
useBorder emits the global .origam--border-{none,thin,thick} utility for these keywords, and that utility paints correctly wherever nothing competes with it. But it cannot be the mechanism on its own. A Vue scoped rule (.origam-btn[data-v-hash]) has specificity (0,2,0); a utility (.origam--border-thick) has (0,1,0), so a component that paints from border-width: var(--origam-{cmp}---border-width, …) outranks it regardless of which sheet loads last — this is specificity, not order.
Measured across the catalogue: 10 of the 43 useBorder consumers carry such a rule (Btn, List, Kbd, Code, CardHeader, CardText, Audio, Calendar, Container, Row). On every one of them border="thick" painted 1px and border="none" painted 1px instead of cancelling.
The fix is not per-component SCSS. The keywords resolve to a width, so useBorder emits them on the same inline channel the numeric :border="4" form always used — which is exactly why the numeric case never had this bug. Widths come from BORDER_KEYWORD_WIDTH, the same tokens the utility declares, so the class and the inline copy cannot drift apart. A direction (border="top") emits all four physical widths — thin on the named side, 0 on the other three — because components that paint from a single border-width shorthand own no per-side custom property a class could target.
When #514 settles the foreground-token question and the DS adopts @layer (measured in packages/tests/e2e/btn-cascade-layer-probe.spec.ts), the utility wins on its own and this inline path is the thing to delete.
Polymorphic tag
vue
<template>
<!-- Renders as <a href="…"> -->
<OrigamBtn tag="a" href="/docs" text="Docs" />
<!-- Renders as a router-link automatically when `to` is set -->
<OrigamBtn :to="{ name: 'home' }" text="Home" />
</template>Slots
| Slot | Slot props | Description |
|---|---|---|
default | — | Override the inner content entirely. |
prepend | — | Replace the prepend icon / avatar slot. |
append | — | Replace the append icon / avatar slot. |
loader | progressProps | Replace the spinner / strip shown when loading is active. |
wrapper | — | Replace EVERYTHING inside the button (advanced). |
vue
<template>
<OrigamBtn>
<template #prepend>
<OrigamIcon icon="mdi-heart" />
</template>
Full custom <strong>content</strong>
<template #append>
<OrigamIcon icon="mdi-arrow-right" />
</template>
</OrigamBtn>
</template>Emits
| Event | Payload | Description |
|---|---|---|
click | MouseEvent | Standard button click. Fires for <a> tags too. |
group:selected | { value: boolean } | The button's selection inside its group changed — value is the new state. Only fires when the button is registered in a group. <OrigamBtnToggle> is the only component that provides one (ORIGAM_BTN_TOGGLE_KEY) — <OrigamBtnGroup> is purely visual and does not. A button outside a toggle calls useGroupItem(…, false), gets null, and never registers the watcher, so nothing is ever emitted. Inside one, the emit comes from useGroupItem's watch(isSelected, …), so a programmatic change to the toggle's modelValue fires it exactly like a click. |
update:hover | boolean | v-model companion of the hover prop: true on mouseenter, false on mouseleave. Declared since #1152 — it was emitted before, undeclared, and Vue warned on every hover. |
vue
<template>
<OrigamBtn prepend-icon="mdi-close" text="Cancel" @click="onCancel"/>
</template>click:prepend / click:append were removed (#443, #577)
<OrigamBtn> no longer emits them at all — the prepend/append <span> carries no click listener any more. They never worked for a keyboard user: the emit was bound to the origam-btn__prepend / origam-btn__append<span>, while a keyboard activation synthesises its click on the button ROOT — a listener bound to a descendant never sees it. Anyone navigating by keyboard, and every assistive technology driving the button that way, simply could not trigger the action.
The remedy applied to the ten other useAdjacent consumers — promote the zone to a role="button" tab stop when a listener is attached — cannot be used here. <OrigamBtn> renders as <button> or <a>, and the HTML content model for both forbids an interactive-content descendant and any descendant carrying tabindex. A nested <button type="button"> is invalid at that position for the same reason.
The shape was wrong, not just the markup: a control that already owns one action cannot host a second. Two actions are two buttons.
vue
<template>
<origam-btn-group>
<origam-btn text="Cancel" @click="onCancel"/>
<origam-btn icon="mdi-close" :aria-label="t('btn_dismiss', 'Dismiss')" @click="onCloseIcon"/>
</origam-btn-group>
</template>The prepend / append slots are unaffected and remain the right way to put a decorative or informational icon inside a button.
Props (interface)
ts
interface IBtnProps extends ICommonsComponentProps,
IColorProps, IBorderProps, IDensityProps, IDimensionProps,
IElevationProps, IRoundedProps, ITagProps, ISizeProps,
ILinkProps, IRippleProps, IControlLoaderProps, IPositionProps,
ILocationProps, IGroupItemProps, IPaddingProps, IMarginProps,
IAdjacentProps, IStatusProps, IHoverProps, ITypographyProps {
active?: boolean
flat?: boolean
icon?: boolean | TIcon
block?: boolean
slim?: boolean
stacked?: boolean
wrap?: boolean
text?: string
}| Prop | Type | Default | Description |
|---|---|---|---|
wrap | boolean | false | Lets the label wrap onto several lines (white-space: normal, centred) instead of staying on one nowrap line. Emits the origam-btn--wrap class. Like every prop, it can be set for a whole theme through theme.components['origam-btn']. |
Height is a minimum
A button's height is a minimum, not a fixed value: the box is height: auto with min-height set to the size token (--origam-btn---height + --origam-btn---density). A button whose content fits on one line keeps exactly the height its size and density give it; it only grows when its content is taller than that minimum — typically a wrap label on two lines.
- The
heightprop still wins: it is written inline, so a fixedheight="60"stays fixed and the content overflows or is clipped as before. --origam-btn---min-heightcan raise the minimum (a marketing layout sets it to 44 px). Setting it to0removes the minimum — the button then shrinks to its content — so do not write it to "reset" the height.- Icon-only buttons (
icon) keep a fixed, square box: their width derives from the same token, and no label can overflow. - The vertical padding is read from
--origam-btn---padding-block(declared as0px, so a button that does not set it does not move). Set it on the button or on an ancestor to give a wrapped label some air; it has no effect oniconbuttons. - The content is centred vertically inside that minimum, whatever the rendered tag. The root is
display: inline-flexwithalign-items: center(andflexwithblock, or once a flex/grid parent blockifies it). It stays inline-level, so a button inside a plain paragraph keeps the width of its content. From 2.29.1 to 2.32.1, a button rendered as an<a>(href/to) had its label stuck to the top of the box (#1168); a native<button>hid the defect because the browser centres its content itself.
vue
<template>
<!-- The button grows to hold its wrapped lines plus 8px of padding above and below -->
<OrigamBtn
block
wrap
:style="{ '--origam-btn---padding-block': '8px' }"
text="Enregistrer et continuer vers la page de confirmation"
/>
</template>Typography
The font props come from the shared ITypographyProps surface (wired by the useTypography composable). Each one re-points the matching --origam-btn---* variable at a primitive font token, so a single button can override its theme typography without custom CSS. Unset props keep the theme / size value.
| Prop | Type | Default | Description |
|---|---|---|---|
fontSize | TFontSize | — | Sets --origam-btn---font-size to var(--origam-font__size---{fontSize}) (xs → 5xl). Overrides the size-variant font-size when set. |
fontWeight | TFontWeight | — | Sets --origam-btn---font-weight to var(--origam-font__weight---{fontWeight}) (regular 400 → black 900). |
lineHeight | TLineHeight | — | Sets --origam-btn---line-height to var(--origam-font__lineHeight---{lineHeight}) (none 1 → loose 2). |
letterSpacing | TLetterSpacing | — | Sets --origam-btn---letter-spacing to var(--origam-font__letterSpacing---{letterSpacing}) (tight → widest). |
fontFamilywas removed fromIBtnProps(issue #501): the component's SCSS has nofont-familyrule, andfontFamilyis a project-level setting configured once onOrigamApp— not a per-instance override. UsefontFamilyon text components (OrigamTitle,OrigamCode, …) where it still has an effect.
Anatomy
html
<button class="origam-btn origam-btn--{intent} origam-btn--size-{size}">
<span class="origam-btn__overlay" /> <!-- hover/focus tint -->
<span class="origam-btn__underlay" /> <!-- elevation shadow -->
<span class="origam-btn__loader">
<span class="origam-btn__prepend">
<!-- prepend icon / avatar / slot -->
</span>
<span class="origam-btn__content">
<!-- text or default slot -->
</span>
<span class="origam-btn__append">
<!-- append icon / avatar / slot -->
</span>
</span>
</button>Aligning the content to the start
The label is centred by default. A text button used as a link inside a sentence can flow like start-aligned text by setting the two content tokens (both are needed once a wrap label spans several lines):
vue
<OrigamBtn
variant="text"
wrap
text="Guillaume Boutin"
:style="{ '--origam-btn__content---justify-content': 'flex-start', '--origam-btn__content---text-align': 'start' }"
/>Design tokens consumed
<OrigamBtn> reads its variables from packages/ds/src/assets/css/tokens/light.css and dark.css (SCSS twins under packages/ds/src/assets/scss/tokens/) — the --origam-btn---* prefix (and --origam-btn-group---* when grouped). Override at the document root or via a :style binding to re-skin a single instance.
| CSS variable | Token reference |
|---|---|
--origam-btn---background-color | {color.action.secondary.bg} |
--origam-btn---color | {color.action.secondary.fg} |
--origam-btn---background-color-hover | {color.action.secondary.bgHover} |
--origam-btn---border-radius | {radius.sm} |
--origam-btn---border-color | currentColor (outlined variant; overridable via borderColor prop) |
--origam-btn---border-compensation | 0px; set by outlined / ghost to their outline width and subtracted from padding-inline (internal, do not set) |
--origam-btn---background-color-text-active | transparent by default: set it to give the text variant an active (active / selected) fill |
--origam-btn__content---justify-content | center — main-axis alignment of the label block; set flex-start to align it to the start |
--origam-btn__content---text-align | center — alignment of the lines of a wrap label; set start to align them to the start |
--origam-btn---border-color-ghost | color-mix(currentColor 24%) (ghost variant) |
--origam-btn---font-size | {font.size.md} |
--origam-btn---font-weight | {font.weight.medium} |
--origam-btn---transition-duration | {motion.duration.slow} |
--origam-btn--{intent}---background-color | {color.action.{intent}.bg} |
The full list lives in packages/ds/src/assets/css/tokens/light.css and dark.css — grep for --origam-btn.
Accessibility
✅ Full keyboard support (Enter, Space).
✅
aria-busy="true"andaria-disabled="true"while a loader is active (lineorcircular). Both are absent when idle, so noaria-busy="false"is added to the accessibility tree. The label stays in the DOM, so the accessible name is unchanged, and the nativedisabledis NOT set: the button keeps focus.✅ Focus ring uses
--origam-color__border---focus(theme-aware).⚠️
disabledis conveyed differently per tag, on purpose:tag="button"(the default) gets the nativedisabledattribute. Noaria-disabledis emitted — it would be redundant, and the ARIA spec's first rule is that a native element beats an ARIA attribute.tag="a"has no nativedisabled, so the anchor getsaria-disabled="true"and itshrefis dropped instead.
⚠️ Icon-only mode needs an
aria-labelyou supply yourself. The component does not derive one from theiconprop, and there is noariaLabelprop: an icon name (mdi-content-save) is an identifier, not a translated human label, so auto-filling it would produce exactly the "bad ARIA" the W3C tells you is worse than none. Pass it through — it falls through to the root element with the rest of$attrs:vue<origam-btn icon="mdi-content-save" :aria-label="t('btn_save', 'Save')"/>⛔ #653 — this is now enforced by a dev-time warning, not just by this paragraph. #427 was closed as fixed while its own closing commit stated in writing that this finding was out of scope, so the defect survived a ticket that claimed to have handled it. An icon-only
<origam-btn>with noaria-label/aria-labelledby/titlenow logs, once per component in development builds:[origam] <OrigamBtn> renders a control with no accessible name: icon-only mode renders a <button> whose only content is an aria-hidden glyph. Add aria-label (or aria-labelledby) …The
<button>itself is not withdrawn, and no label is invented. Unlike a prepend/append zone — where the DS addsrole="button"itself and can therefore decline to (seeuseAccessibleCommand, #747) — this element IS a button. axe will keep reportingbutton-name(impactcritical) until the consumer supplies the name, which is the correct outcome: the missing text is theirs to provide.
Theming notes
- The component is theme-aware out of the box. Switching
<html data-theme="dark">re-resolves every variable instantly — no Vue re-render required. - A sub-tree can opt into a different theme via
<OrigamThemeProvider>.
Related
OrigamBtnGroup— segmented control / toolbar group.OrigamBtnToggle— single-pick or multi-pick toggle group.useColorEffect— composable that drives the intent → token resolution.