Skip to content

OrigamCard ​

<OrigamCard> is a flagship surface component that composes a clickable or static content container with optional header, asset image, text body, and footer. It supports the full gamut of layout, styling, and accessibility features via composable prop mixins.

Basic usage ​

vue
<template>
    <OrigamCard title="Card title" text="Supporting text." />
</template>

Pass title, subtitle, prependIcon, appendIcon, prependAvatar, or appendAvatar to populate the header automatically. Use the named header slots for full control.

vue
<template>
    <OrigamCard
        title="Profile"
        subtitle="Active account"
        prepend-icon="mdi-account"
    />
</template>

Asset / image ​

vue
<template>
    <OrigamCard
        image="https://picsum.photos/600/300"
        title="Image card"
    />
</template>
vue
<template>
    <OrigamCard
        link
        href="https://origam.dev"
        title="Click me"
    />
</template>

ICardProps extends ILinkProps, so the four router-link props are real and forwarded to vue-router's own useLink.

PropTypeEffect
hrefstringRenders the root as <a href>. No router involved.
toRouteLocationRawRenders as <a> with the resolved route href and navigates on click through the router.
replacebooleanWith to, navigates with router.replace() instead of router.push() — no history entry.
exactbooleanNarrows the active-state derivation to an exact match, query string included.
linkbooleanForces the clickable affordance (cursor, ripple, --link modifier) without a URL.
vue
<template>
    <OrigamCard :to="{ name: 'invoice', params: { id } }" replace title="Open invoice"/>
</template>

replace, to and exact need an installed router. useLink resolves RouterLink dynamically; when the app has no vue-router instance the resolution falls back to a plain string and the composable returns early with only href. That is exactly the case inside the Histoire sandbox — the Replace / To / Exact controls in the story's Link group are inert there, not because the props are dead but because the sandbox installs no router. With a router present, replace: true routes through router.replace() (verified in packages/tests/TU/components/Card/OrigamCard.link.spec.ts).

Loading state ​

Accepts a boolean or a number (progress percentage) for loading.

vue
<template>
    <OrigamCard loading title="Fetching data…" />
    <OrigamCard :loading="75" title="75 % loaded" />
</template>

loadingText names what the loading indicator announces to a screen reader. It carries a locale key, not final text — it is handed to the active renderer's label prop (<OrigamProgress> or <OrigamSkeleton>), which resolves it through the DS t() mechanism. Defaults to the shared 'origam.loading' key. A raw string that matches no key is returned unchanged, so loading-text="Fetching your invoices" also works if you prefer to translate on your side.

vue
<template>
    <OrigamCard loading loading-text="origam.data_iterator.loading_text" />
</template>

A per-instance loading="{ type: 'line', label: '…' }" still wins over loadingText.

Skeleton silhouette ​

loading="{ type: 'skeleton' }" draws the card's own anatomy — media, title, subtitle, two text lines, actions — as light <OrigamSkeleton> primitives inside ONE <OrigamSkeletonGroup>: a single role="status" announcement for the whole card, a single pulse clock, no wrapper, no per-instance <style>. Only the parts the card has are drawn: the media block when there is an image or an #asset slot (it keeps the --origam-card__asset---aspect-ratio of the real media), the two actions when there is a #footer slot. The real content is not rendered while the skeleton shows.

The overrides of the config reach the right target: animation and label go to the group, color, bgColor and rounded to every primitive (so the silhouette stays themable by props). The padding of the silhouette is --origam-card__skeleton---padding.

vue
<template>
    <OrigamCard
        :loading="{ type: 'skeleton' }"
        image="cover.jpg"
    >
        <template #footer>Actions</template>
    </OrigamCard>
</template>

The former variant="card" template is no longer used by the card.

Disabled ​

vue
<template>
    <OrigamCard disabled title="Cannot interact" />
</template>

Hover elevation ​

Add the hover boolean to lift the card on pointer-over.

vue
<template>
    <OrigamCard hover title="Hover me" />
</template>

hover is IHoverProps (boolean | IStateEffectConfig): pass an object to restyle the card ONLY while the pointer is over it. Hover is ignored on a flat or disabled card, so set :flat="false" under a theme that defaults to flat.

vue
<template>
    <OrigamCard :flat="false" border="thin" :hover="{ borderColor: 'var(--origam-color__border---strong)' }" title="Hover me" />
</template>

A highlighted card needs no dedicated prop: border + borderColor (and active for a pressed / selected state) cover it.

Content wrapper ​

The default and text slots are wrapped in .origam-card__content. When the card is itself a grid or flex container, that wrapper stands between it and your children. Set contentDisplay="contents" to flatten it so the children become direct items of the card's layout:

vue
<template>
    <OrigamCard content-display="contents" style="display: grid; grid-template-columns: 1fr 1fr">
        <span>A</span>
        <span>B</span>
    </OrigamCard>
</template>
PropValuesEffect
contentDisplayblock (default), contents, flex, griddisplay of .origam-card__content, painted inline on the wrapper itself. Themable through theme.components['origam-card'].

For a theme-wide default, set the token --origam-card__content---display instead. Do not confuse it with flat, which only removes the shadow.

Flat ​

Remove shadow with flat.

vue
<template>
    <OrigamCard flat title="No shadow" />
</template>

Elevation ​

elevation accepts three shapes:

  • An origam-native rung name — 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' — resolves to var(--origam-shadow---{rung}).
  • A Material-style number — 0..24 — bucketised onto the origam shadow ladder.
  • A free-form custom box-shadow value — var(...), calc(...), a literal shadow list, multiple comma-separated layers, inset, … — emitted verbatim.
vue
<template>
    <OrigamCard :elevation="8" title="Elevated card" />
    <OrigamCard elevation="lg" title="Elevated card (named rung)" />
    <OrigamCard elevation="0 4px 12px rgba(0,0,0,.24)" title="Custom box-shadow" />
</template>

The custom form is detected permissively (same approach as the rounded free-form escape hatch): any string that isn't a named rung and doesn't parse as 0..24 is treated as a custom box-shadow if it carries at least one shadow-like signal — a CSS function call (var(, calc(, rgba(, …), a hex color, a length with a unit, or inset. Anything else falls through to the pre-existing behaviour (no shadow emitted). See useElevation (src/composables/Commons/elevation.composable.ts) for the full resolution order.

Rounded ​

vue
<template>
    <OrigamCard rounded="large" title="Rounded card" />
</template>

The origam-card--rounded-* class is a hook for consumers; the radius itself is painted by the inline declaration on the root.

Each corner can be overridden individually. A corner prop beats the rounded shorthand for that corner only:

vue
<template>
    <OrigamCard rounded="lg" rounded-top-left="0px" title="One flat corner" />
</template>
PropEffet
roundedTopLeftCoin haut-gauche uniquement
roundedTopRightCoin haut-droit uniquement
roundedBottomLeftCoin bas-gauche uniquement
roundedBottomRightCoin bas-droit uniquement

Même vocabulaire que rounded : 8, '8px', 'md', 'large', 'var(…)'.

Padding et margin ​

Les deux raccourcis se déclinent par axe logique et par côté physique :

vue
<template>
    <OrigamCard padding="16px" padding-left="32px" title="Un seul côté ajusté" />
</template>
GroupeProps
Padding — axepaddingBlock paddingInline
Padding — côtépaddingTop paddingRight paddingBottom paddingLeft
Margin — axemarginBlock marginInline
Margin — côtémarginTop marginRight marginBottom marginLeft

Le côté physique gagne sur l'axe, qui gagne sur le raccourci. Les valeurs acceptées et la table de précédence complète sont documentées dans Espacement et coins.

Border ​

vue
<template>
    <OrigamCard border title="Bordered card" />
</template>

Border — per side ​

borderTop / borderRight / borderBottom / borderLeft set an independent width (and optionally style/color, via a free-form string like "2px dashed red") for a single physical side, and borderTopColor / borderRightColor / borderBottomColor / borderLeftColor set an independent color for that side (accepts a semantic intent — 'primary', 'danger', … — or a raw CSS color; gradients are not supported on border colors and are silently ignored).

vue
<template>
    <OrigamCard
        :border-top="4"
        :border-right="2"
        :border-bottom="4"
        :border-left="2"
        border-top-color="danger"
        border-right-color="primary"
        border-bottom-color="success"
        border-left-color="info"
        title="Per-side border"
    />
</template>

Precedence (specific beats global, per physical side): the global border shorthand resolves first, then the standalone borderColor / borderStyle, then the per-side borderTop / borderRight / borderBottom / borderLeft, and finally the per-side *Color props win last. Each rung only overrides the side(s) it actually targets — e.g. border="1px solid black" with borderTop="4px dashed red" renders a 4px dashed red top edge while the other three sides stay 1px solid black.

Density ​

vue
<template>
    <OrigamCard density="compact" title="Compact card" />
</template>

Slots ​

SlotSlot propsDescription
wrapper—Full override of all internal content.
loader—Custom loader element (replaces the progress bar).
header—Replaces the entire auto-generated header.
header.prepend—Prepend content inside the header.
header.append—Append content inside the header.
header.title—Title content inside the header.
header.subtitle—Subtitle content inside the header.
header.content—Body of the header.
asset—Replaces the image container.
text—Replaces the OrigamCardText text region.
default—Main body content.
footer—Footer area below the body.

Events ​

NamePayloadWhen
click:prependMouseEventClick on the prepend icon/avatar in the header.
click:appendMouseEventClick on the append icon/avatar in the header.

Design tokens ​

CSS variableDescription
--origam-card---backgroundCard background color.
--origam-card---colorCard text color.
--origam-card---box-shadowShadow layer.
--origam-card---border-radiusBorder radius (composed from four corner tokens).
--origam-card---border-colorBorder color.
--origam-card---border-widthBorder width.
--origam-card---padding-block-startBlock-start padding.
--origam-card---padding-block-endBlock-end padding.
--origam-card---densityDensity modifier (added to each padding axis).
--origam-card---transition-durationHover / focus transition timing.
--origam-card__content---displaydisplay of the content wrapper (block by default; contents flattens it).
--origam-card__overlay---opacityOverlay scrim opacity on hover / focus.

Accessibility ​

  • When link is true the card is rendered as an anchor element and is keyboard-reachable.
  • disabled sets tabindex="-1" and pointer-events: none.
  • The card never assumes an implicit ARIA role; authors must add role="article" or similar when the content requires it.