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.
Aperçu
Rendu de l’aperçu en cours…
containRendu de l’aperçu en cours…
coverRendu de l’aperçu en cours…
roundedStructure
Anatomie
Décomposition visuelle de la structure interne du composant avec les appels de classes BEM.
<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
Toutes les props acceptées par ce composant, avec leur type, valeur par défaut et 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
Emplacements de contenu exposés par ce composant.
- #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
Événements émis par ce composant.
- @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
Membres exposés
Propriétés et méthodes accessibles via ref template (defineExpose). Utilisés pour le contrôle programmatique.
- <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).
Personnalisation
Variables CSS
Propriétés CSS personnalisées exposées par ce composant. Surchargez-les pour personnaliser sans perdre la compatibilité avec le thème.
- 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
Accessibilité
Rôles ARIA, navigation clavier et gestion du focus. Sourcé depuis le template réel du composant.
Rôles ARIA
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.
Interactif
Playground
Modifiez les props en direct et observez le composant se mettre à jour. Le snippet de code généré suit vos changements.
Rendu de l’aperçu en cours…
Usage
Exemples
Extraits de code prêts à coller dans vos templates.
Basic image
vue Lazy loading with blur placeholder
vue Gradient overlay with slot
vue