Appearance
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>Header
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>Clickable (link)
vue
<template>
<OrigamCard
link
href="https://origam.dev"
title="Click me"
/>
</template>Link props
ICardProps extends ILinkProps, so the four router-link props are real and forwarded to vue-router's own useLink.
| Prop | Type | Effect |
|---|---|---|
href | string | Renders the root as <a href>. No router involved. |
to | RouteLocationRaw | Renders as <a> with the resolved route href and navigates on click through the router. |
replace | boolean | With to, navigates with router.replace() instead of router.push() — no history entry. |
exact | boolean | Narrows the active-state derivation to an exact match, query string included. |
link | boolean | Forces the clickable affordance (cursor, ripple, --link modifier) without a URL. |
vue
<template>
<OrigamCard :to="{ name: 'invoice', params: { id } }" replace title="Open invoice"/>
</template>
replace,toandexactneed an installed router.useLinkresolvesRouterLinkdynamically; when the app has novue-routerinstance the resolution falls back to a plain string and the composable returns early with onlyhref. That is exactly the case inside the Histoire sandbox — theReplace/To/Exactcontrols 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: trueroutes throughrouter.replace()(verified inpackages/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>| Prop | Values | Effect |
|---|---|---|
contentDisplay | block (default), contents, flex, grid | display 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 tovar(--origam-shadow---{rung}). - A Material-style number —
0..24— bucketised onto the origam shadow ladder. - A free-form custom
box-shadowvalue —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>| Prop | Effet |
|---|---|
roundedTopLeft | Coin haut-gauche uniquement |
roundedTopRight | Coin haut-droit uniquement |
roundedBottomLeft | Coin bas-gauche uniquement |
roundedBottomRight | Coin 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>| Groupe | Props |
|---|---|
| Padding — axe | paddingBlock paddingInline |
| Padding — côté | paddingTop paddingRight paddingBottom paddingLeft |
| Margin — axe | marginBlock 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
| Slot | Slot props | Description |
|---|---|---|
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
| Name | Payload | When |
|---|---|---|
click:prepend | MouseEvent | Click on the prepend icon/avatar in the header. |
click:append | MouseEvent | Click on the append icon/avatar in the header. |
Design tokens
| CSS variable | Description |
|---|---|
--origam-card---background | Card background color. |
--origam-card---color | Card text color. |
--origam-card---box-shadow | Shadow layer. |
--origam-card---border-radius | Border radius (composed from four corner tokens). |
--origam-card---border-color | Border color. |
--origam-card---border-width | Border width. |
--origam-card---padding-block-start | Block-start padding. |
--origam-card---padding-block-end | Block-end padding. |
--origam-card---density | Density modifier (added to each padding axis). |
--origam-card---transition-duration | Hover / focus transition timing. |
--origam-card__content---display | display of the content wrapper (block by default; contents flattens it). |
--origam-card__overlay---opacity | Overlay scrim opacity on hover / focus. |
Accessibility
- When
linkis true the card is rendered as an anchor element and is keyboard-reachable. disabledsetstabindex="-1"andpointer-events: none.- The card never assumes an implicit ARIA role; authors must add
role="article"or similar when the content requires it.