Skip to content

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):

valuerendered
(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 ​

SlotSlot propsDescription
default—Override the inner content entirely.
prepend—Replace the prepend icon / avatar slot.
append—Replace the append icon / avatar slot.
loaderprogressPropsReplace 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 ​

EventPayloadDescription
clickMouseEventStandard 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:hoverbooleanv-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
}
PropTypeDefaultDescription
wrapbooleanfalseLets 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 height prop still wins: it is written inline, so a fixed height="60" stays fixed and the content overflows or is clipped as before.
  • --origam-btn---min-height can raise the minimum (a marketing layout sets it to 44 px). Setting it to 0 removes 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 as 0px, 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 on icon buttons.
  • The content is centred vertically inside that minimum, whatever the rendered tag. The root is display: inline-flex with align-items: center (and flex with block, 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.

PropTypeDefaultDescription
fontSizeTFontSize—Sets --origam-btn---font-size to var(--origam-font__size---{fontSize}) (xs → 5xl). Overrides the size-variant font-size when set.
fontWeightTFontWeight—Sets --origam-btn---font-weight to var(--origam-font__weight---{fontWeight}) (regular 400 → black 900).
lineHeightTLineHeight—Sets --origam-btn---line-height to var(--origam-font__lineHeight---{lineHeight}) (none 1 → loose 2).
letterSpacingTLetterSpacing—Sets --origam-btn---letter-spacing to var(--origam-font__letterSpacing---{letterSpacing}) (tight → widest).

fontFamily was removed from IBtnProps (issue #501): the component's SCSS has no font-family rule, and fontFamily is a project-level setting configured once on OrigamApp — not a per-instance override. Use fontFamily on 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 variableToken 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-colorcurrentColor (outlined variant; overridable via borderColor prop)
--origam-btn---border-compensation0px; set by outlined / ghost to their outline width and subtracted from padding-inline (internal, do not set)
--origam-btn---background-color-text-activetransparent by default: set it to give the text variant an active (active / selected) fill
--origam-btn__content---justify-contentcenter — main-axis alignment of the label block; set flex-start to align it to the start
--origam-btn__content---text-aligncenter — alignment of the lines of a wrap label; set start to align them to the start
--origam-btn---border-color-ghostcolor-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" and aria-disabled="true" while a loader is active (line or circular). Both are absent when idle, so no aria-busy="false" is added to the accessibility tree. The label stays in the DOM, so the accessible name is unchanged, and the native disabled is NOT set: the button keeps focus.

  • ✅ Focus ring uses --origam-color__border---focus (theme-aware).

  • ⚠️ disabled is conveyed differently per tag, on purpose:

    • tag="button" (the default) gets the native disabled attribute. No aria-disabled is 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 native disabled, so the anchor gets aria-disabled="true" and its href is dropped instead.
  • ⚠️ Icon-only mode needs an aria-label you supply yourself. The component does not derive one from the icon prop, and there is no ariaLabel prop: 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 no aria-label / aria-labelledby / title now 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 adds role="button" itself and can therefore decline to (see useAccessibleCommand, #747) — this element IS a button. axe will keep reporting button-name (impact critical) 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>.
  • OrigamBtnGroup — segmented control / toolbar group.
  • OrigamBtnToggle — single-pick or multi-pick toggle group.
  • useColorEffect — composable that drives the intent → token resolution.