Img
Responsive image component with lazy loading, aspect-ratio enforcement, placeholder and error slot, optional gradient overlay, srcset / sizes support, and a smooth fade-in transition on load.
Preview
Rendering the live preview…
containRendering the live preview…
coverRendering the live preview…
roundedStructure
Anatomy
Visual breakdown of the component's internal structure with BEM class call-outs.
<origam-img> — 5 internal parts. The root ① wraps OrigamResponsive for aspect-ratio enforcement. The picture ② is absolutely positioned. Placeholder ③ and error ④ layers are conditional. The gradient ⑤ is an absolute div when the gradient prop is set.- 1.origam-img
- Root element wrapping OrigamResponsive. Carries role="img" when alt is present. Has --booting modifier until aspectRatio resolves.
- 2.origam-img__picture
- Native
element. Absolutely positioned, 100% width/height. Has --cover (object-fit: cover) or --contain (object-fit: contain) modifier. Has --preload modifier with blur filter when showing lazySrc.
- 3.origam-img__placeholder
- Shown during loading (or lazySrc phase) when the #placeholder slot is provided. Absolutely positioned layer behind the main image.
- 4.origam-img__error
- Shown when the image fails to load and the #error slot is provided.
- 5.origam-img__gradient
- Absolutely positioned rendered when gradient prop is set. Applies background-image: linear-gradient(...).
API
Props
All props accepted by this component, with their type, default value and description.
- altstring
- Alt text for the image. When provided, sets role="img" on the root element. Leave undefined only for purely decorative images (aria-hidden is set by the consumer in that case).
- coverbooleanfalse
- Sets object-fit: cover on the picture element. Default is object-fit: contain.
- draggableboolean
- HTML draggable attribute on the <img> element.
- gradientstring
- CSS gradient string applied as an overlay on top of the image. Example: "to bottom, rgba(0,0,0,0), rgba(0,0,0,0.5)".
- lazySrcstring
- Low-quality placeholder URL shown while the full src loads. Displayed with a blur filter (--preload modifier).
- optionsIIntersectionObserverInit
- IntersectionObserver options (rootMargin, threshold) for fine-tuning when the lazy load triggers.
- sizesstring
- Native <img> sizes attribute for Art Direction with srcset.
- srcstring | ISrcObject
- Image URL, or an ISrcObject with { src, srcset, lazySrc, aspectRatio }. Both forms are accepted; the object form is used by Avatar to bundle all image metadata.
- crossorigin
- CORS attribute on the <img> element. Values: 'anonymous' | 'use-credentials'.
- referrerpolicy
- Referrer policy on the <img> element (e.g. "no-referrer", "strict-origin-when-cross-origin").
- srcsetstring
- Native <img> srcset attribute for resolution switching.
- positionstring
- Sets object-position on the picture element for focal-point control (e.g. "top center").
- colorTColor
- bgColor
- Background colour shown while the image is loading or on error.
- aspectRatiostring | number
- Forces the image container to a specific aspect ratio (e.g. "16/9" or 1.777). Prevents layout shift before the image loads.
- contentClassstring
- heightnumber | string
- Container height override.
- maxHeightnumber | string
- maxWidthnumber | string
- minHeightnumber | string
- minWidthnumber | string
- widthnumber | string
- Container width override.
- idstring
- classstring | Array<string> | object
- stylestring | Array<string> | object | StyleValue
- tagstring
- paddingboolean | number | string
- paddingTopboolean | number | string
- paddingLeftboolean | number | string
- paddingBottomboolean | number | string
- paddingRightboolean | number | string
- paddingBlockboolean | number | string
- paddingInlineboolean | number | string
- paddingInlineStartboolean | number | string
- paddingInlineEndboolean | number | string
- paddingBlockStartboolean | number | string
- paddingBlockEndboolean | number | string
- marginboolean | number | string
- marginTopboolean | number | string
- marginLeftboolean | number | string
- marginBottomboolean | number | string
- marginRightboolean | number | string
- marginBlockboolean | number | string
- marginInlineboolean | number | string
- marginInlineStartboolean | number | string
- marginInlineEndboolean | number | string
- marginBlockStartboolean | number | string
- marginBlockEndboolean | number | string
- borderboolean | number | string | TDirectionBoth | Array<TDirectionBoth>
- borderTopboolean | number | string
- borderLeftboolean | number | string
- borderBottomboolean | number | string
- borderRightboolean | number | string
- borderBlockboolean | number | string
- borderInlineboolean | number | string
- borderInlineStartboolean | number | string
- borderInlineEndboolean | number | string
- borderBlockStartboolean | number | string
- borderBlockEndboolean | number | string
- borderColorstring
- borderStylestring
- borderTopColorTColor
- borderRightColorTColor
- borderBottomColorTColor
- borderLeftColorTColor
- borderInlineStartColorTColor
- borderInlineEndColorTColor
- borderBlockStartColorTColor
- borderBlockEndColorTColor
- roundedboolean | number | string | TRounded | null | undefined
- roundedTopRightboolean | number | string
- roundedTopLeftboolean | number | string
- roundedBottomLeftboolean | number | string
- roundedBottomRightboolean | number | string
- roundedStartStartboolean | number | string
- roundedStartEndboolean | number | string
- roundedEndStartboolean | number | string
- roundedEndEndboolean | number | string
- transitionboolean | string | TTransitionProps'fade-transition'
- Vue transition name for the fade-in effect when the image loads. Set to false to disable.
- eagerbooleanfalse
- When true, loads the image immediately without waiting for it to enter the viewport (disables IntersectionObserver-based lazy loading).
API
Slots
Content slots exposed by this component.
- #placeholder
- Shown while the image is loading (before the load event fires) or while lazySrc is displayed. Typically a skeleton or a low-resolution blur.
- #error
- Shown when the image fails to load (error event). Typically an error icon or a fallback image.
- #default
- Overlay content rendered on top of the image (e.g. a caption, a play button, badges). Positioned absolutely over the image surface.
API
Emits
Events emitted by this component.
- @loadstart{ src: string }
- Fired before the network request begins. Provides the resolved src.
- @load{ src: string }
- Fired when the image is fully decoded and rendered. Provides the resolved currentSrc or src.
- @error{ src: string }
- Fired when the browser cannot load the image (network error, 404, CORS block). Provides the attempted src.
API
Exposed members
Properties and methods accessible via template ref (defineExpose). Use them for programmatic control.
- <T extends object>(props: T, exclude?: string[]) => Partial<T>
- Filters and forwards a subset of props.
- Ref<string>
- Reactive CSS string generated by useStyle.
- string
- Unique style-sheet ID for this instance.
- () => void
- Injects the computed style sheet into the document.
- () => void
- Removes the injected style sheet.
- ComputedRef<boolean>
- True when the image has successfully loaded (state === LOADED).
- Ref<boolean>
- True once the component style sheet has been injected. Note: distinct from isLoaded (image load state).
Customisation
CSS variables
CSS custom properties exposed by this component. Override them to customise the component without losing theme compatibility.
- Background colour of the image container while the image loads.
- Corner radius of the image root. Overridden by the rounded prop.
- Fade-in transition duration when the image loads.
- CSS filter applied to the lazySrc placeholder image.
- object-fit value for the --contain modifier.
- object-fit value for the --cover modifier.
Inclusion
Accessibility
ARIA roles, keyboard navigation and focus management. Sourced from the real component template.
ARIA roles
imgNotes
- Always provide a meaningful alt text. When alt is present, role="img" and aria-label={alt} are set on the root. For decorative images, omit alt and set aria-hidden="true" on the parent.
- Lazy loading is handled via IntersectionObserver (not the native loading="lazy" attribute) so the component loads the image only when it enters the viewport. The placeholder slot is announced by the browser as the alt text is still present on the root.
- When the image fails to load, the #error slot is shown. The slot content should include meaningful text or an icon-with-label so users know the image did not load.
- The fade-in transition respects prefers-reduced-motion. When the user prefers reduced motion, set transition="false" or use --origam-img---transition-duration: 0ms.
Interactive
Playground
Edit props live and see the component update in real time. The generated code snippet updates as you change values.
Rendering the live preview…
Usage
Examples
Ready-to-paste code snippets for your templates.
Basic image
vue Lazy loading with blur placeholder
vue Gradient overlay with slot
vue