Skip to content

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 appearsBehaviour
Hydrated from server HTMLPainted 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> as display: none until the load event, on every render. Now only a client-mounted image waits for load. lazySrc still overlays the image until it has loaded, and the placeholder / error slots are unchanged.

Hydration and loading (#1192) ​

  • No aspect-ratio the server cannot emit. Without an aspect-ratio prop 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 server style and the first client render are identical (no "Hydration style mismatch"). A client-mounted instance applies it at once. An explicit aspect-ratio is deterministic and is rendered by the server.
  • A client-mounted image starts loading when it intersects the viewport. It is display: none until its load, and Chromium never loads a loading="lazy" image that has no box. Once the viewport intersection has fired, the <img> switches to loading="eager" so the load can start; until then it stays lazy. 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 ​

SlotRendered when
defaultAlways — projected on top of the image, behind the gradient.
placeholderWhile the image is loading and lazySrc is not set.
errorWhen 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 ​

EventPayloadDescription
loadstartcurrentSrc: stringNetwork request started.
loadcurrentSrc: stringImage fully decoded.
errorcurrentSrc: stringNative <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.css counterpart, so a dark theme inherits the same values.
  • They land on :root as 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 :root after origam's styles); the component reads it through var() normally.

The defaults themselves are unopinionated (positioning, fit, blur for the lazySrc) so the component blends into any surface.

CSS variablePurpose
--origam-img---z-indexSizer stacking order.
--origam-img--booting---transitionTransition applied while booting.
--origam-img--rounded---border-radiusOverride 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---filterBlur applied to lazySrc.
--origam-img__picture--contain---object-fit / --cover---object-fitobject-fit for each mode.
--origam-img__gradient---*Gradient overlay positioning.
--origam-img__placeholder---*Placeholder slot positioning.
--origam-img__error---*Error slot positioning.

Accessibility ​

  • Pass alt for any meaningful image. The component forwards it to the inner <img> and mirrors it on the wrapper as aria-label when 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.

  • 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.