Appearance
OrigamImg
<OrigamImg> is the lazy-aware, aspect-locked image primitive for origam. It wraps the native <img> element inside an OrigamResponsive sizer so the layout never reflows once the picture finishes loading, and adds the full chrome mixin set (color, rounded, border, padding, margin) that every other origam atom inherits.
It is the engine behind OrigamAvatar (which forces cover + a 1:1 ratio) and the picture surface used by OrigamCard / OrigamHeader.
Basic usage
vue
<template>
<OrigamImg
src="https://picsum.photos/seed/origam/640/360"
:aspect-ratio="16 / 9"
alt="Demo"
/>
</template>Lazy loading
The component uses an IntersectionObserver (via the v-intersect directive) to defer the network request until the image enters the viewport. Pass eager to disable that behaviour, or lazySrc to render a low-resolution preview while the full image loads.
vue
<template>
<OrigamImg
src="https://picsum.photos/seed/origam-large/1600/900"
lazy-src="https://picsum.photos/seed/origam-large/40/22"
:aspect-ratio="16 / 9"
alt="Lazy"
/>
<!-- skip the IntersectionObserver entirely -->
<OrigamImg
src="https://picsum.photos/seed/origam-eager/640/360"
:aspect-ratio="16 / 9"
eager
alt="Eager"
/>
</template>Server rendering and tag (#1182)
The real <img> is part of the server HTML with its src, srcset, sizes and alt, and it is not hidden before hydration: the image shows without JavaScript and the browser's preload scanner can discover it. Native loading="lazy" (or eager when you pass eager) is what defers the request.
The entrance fade depends on how the instance came to exist:
| How the image appears | Behaviour |
|---|---|
| Hydrated from server HTML | Painted at once, no fade, no flash. Only an errored image is hidden, so the error slot replaces it. |
Mounted on the client (SPA navigation, dynamic list, v-if after hydration) | Unchanged: hidden until the native load, then faded in by the transition prop (disabled under prefers-reduced-motion). |
Behaviour change. Until now the server HTML carried the
<img>asdisplay: noneuntil theloadevent, on every render. Now only a client-mounted image waits forload.lazySrcstill overlays the image until it has loaded, and theplaceholder/errorslots are unchanged.
Hydration and loading (#1192)
- No
aspect-ratiothe server cannot emit. Without anaspect-ratioprop the root falls back to the viewport's ratio, which only the browser knows. An instance that hydrates server HTML therefore applies that fallback right after mount, never in its first render, so the serverstyleand the first client render are identical (no "Hydration style mismatch"). A client-mounted instance applies it at once. An explicitaspect-ratiois deterministic and is rendered by the server. - A client-mounted image starts loading when it intersects the viewport. It is
display: noneuntil itsload, and Chromium never loads aloading="lazy"image that has no box. Once the viewport intersection has fired, the<img>switches toloading="eager"so the load can start; until then it stayslazy. A hydrated image is visible and keeps native lazy loading.
The root is a <div> by default, which is not allowed inside a <p>: the HTML parser closes the paragraph before it, and Vue reports a hydration mismatch. Pass tag="span" for phrasing content, such as a Markdown image inside a paragraph. Every element the component renders (root, content wrapper, placeholder, error, gradient) then uses that tag. The box does not change: display comes from --origam-responsive---display (flex), not from the element.
vue
<template>
<p>
Before
<OrigamImg tag="span" src="/a.png" alt="A" :aspect-ratio="16 / 9" />
after.
</p>
</template>Object fit
cover toggles between object-fit: contain (default) and object-fit: cover. Use position to reposition the picture inside the sizer (any valid object-position string).
vue
<template>
<OrigamImg
src="https://picsum.photos/seed/origam-cover/640/360"
:aspect-ratio="1"
cover
position="center top"
alt="Cover, top-aligned"
/>
</template>Aspect ratio
aspectRatio can be a number (16 / 9), a numeric string ('1.7777'), or come from a structured src object that includes its own ratio (so you can ship the metadata alongside the URL). When omitted the sizer falls back to the natural dimensions of the image.
vue
<template>
<OrigamImg
:src="{ src: 'https://picsum.photos/seed/origam-square/400/400', aspectRatio: 1 }"
alt="Square via src object"
/>
</template>Gradient overlay
Pass a CSS gradient string to gradient and the component layers it on top of the picture. Convenient for caption legibility or hero banners.
vue
<template>
<OrigamImg
src="https://picsum.photos/seed/origam-grad/640/360"
:aspect-ratio="16 / 9"
gradient="to bottom, transparent 40%, rgba(0,0,0,0.6) 100%"
alt="Hero with gradient overlay"
/>
</template>Color tinting
Like every origam atom, color and bg-color accept either a TIntent value or a CSS color string. The hex / rgb form is deprecated since v0.4 and emits a one-shot console warning.
vue
<template>
<OrigamImg color="primary" bg-color="surface-overlay" :aspect-ratio="1" />
</template>States & slots
| Slot | Rendered when |
|---|---|
default | Always — projected on top of the image, behind the gradient. |
placeholder | While the image is loading and lazySrc is not set. |
error | When the image errors out. Replaces the placeholder. |
vue
<template>
<OrigamImg :src="brokenUrl" :aspect-ratio="16 / 9" alt="Broken">
<template #error>
<div class="error-state">Failed to load image</div>
</template>
<template #placeholder>
<div class="loading-state">Loading…</div>
</template>
</OrigamImg>
</template>Events
| Event | Payload | Description |
|---|---|---|
loadstart | currentSrc: string | Network request started. |
load | currentSrc: string | Image fully decoded. |
error | currentSrc: string | Native <img> error fired. |
Props (interface)
ts
interface IImgProps extends IColorProps, IResponsiveProps,
ITransitionComponentProps, ILazyProps {
alt?: string
cover?: boolean
draggable?: boolean
gradient?: string
lazySrc?: string
options?: IIntersectionObserverInit
sizes?: string
src?: string | ISrcObject
crossorigin?: TCrossOrigin
referrerpolicy?: TReferrerPolicy
srcset?: string
position?: string
tag?: string // inherited from IResponsiveProps, default 'div'
}
interface ISrcObject {
src?: string
srcset?: string
lazySrc?: string
aspectRatio: number
alt?: string
}Anatomy
html
<!-- the root carries `aspect-ratio` from the `aspectRatio` prop (#709) -->
<!-- element = the `tag` prop (default div); the inner <img> is never display:none before hydration -->
<div class="origam-responsive origam-img">
<img class="origam-img__picture origam-img__picture--cover" />
<div class="origam-img__gradient"></div>
<!-- placeholder / error overlays as needed -->
</div>Design tokens consumed
⛔ <OrigamImg> is NOT yet migrated to the shared token sheets. Its 37 --origam-img* variables are declared in an unscoped <style>:root{…} block at the bottom of packages/ds/src/components/Img/OrigamImg.vue. Grep the four token stylesheets (assets/css/tokens/light.css, dark.css, and their SCSS twins) for --origam-img and you get zero hits — an earlier revision of this page pointed there, which was wrong in both directions: you would not find the defaults, and editing those files would not change the component.
Practical consequences until the migration happens:
- The defaults are theme-independent — there is no
dark.csscounterpart, so a dark theme inherits the same values. - They land on
:rootas soon as the component's style is loaded anywhere on the page, not scoped to the component. - To override, set the variable on your own selector (or on
:rootafter origam's styles); the component reads it throughvar()normally.
The defaults themselves are unopinionated (positioning, fit, blur for the lazySrc) so the component blends into any surface.
| CSS variable | Purpose |
|---|---|
--origam-img---z-index | Sizer stacking order. |
--origam-img--booting---transition | Transition applied while booting. |
--origam-img--rounded---border-radius | Override when rounded is used. |
--origam-img__content---* | Layout of the #default content overlay. |
--origam-img__picture---* | Layout of the inner <img> (position, fit). |
--origam-img__picture--preload---filter | Blur applied to lazySrc. |
--origam-img__picture--contain---object-fit / --cover---object-fit | object-fit for each mode. |
--origam-img__gradient---* | Gradient overlay positioning. |
--origam-img__placeholder---* | Placeholder slot positioning. |
--origam-img__error---* | Error slot positioning. |
Accessibility
- Pass
altfor any meaningful image. The component forwards it to the inner<img>and mirrors it on the wrapper asaria-labelwhen present, so screen readers announce the image regardless of which layer captures focus. - Decorative images should pass
alt=""so AT skip the picture. - The component does not trap focus. If the image acts as a link, wrap it in a focusable element (
<a>,<router-link>).
Theming notes
The component itself only sets neutral chrome (positioning, fit, preload blur). Background tints come from the host surface or the bg-color mixin. Switching <html data-theme="dark"> re-resolves --origam-color__surface---* automatically.
Related
OrigamAvatar— round, fixed-size variant built on top of this component.OrigamResponsive— the underlying aspect-ratio sizer.OrigamTransition— the fade used between loading and loaded states.