Methane@methane-ui/*
CSS LayoutsComponentsSkillsTheme BuilderGitHub
← All Components

<mth-image>

@methane-ui/ui~6.8 KB brotli (cold + Lit)~1.4 KB marginal

Accessible progressive image with safe-URL validation, aspect ratio, lazy loading, placeholder, and fallback handling.

When NOT to use: Use a lightweight @methane-ui/css layout class instead of a custom element when static CSS suffices.

Live Interactive Preview

Interactive StageLive Custom Element · <mth-image> (@methane-ui/ui)
Methane UI · 16:9 Responsive Image Frame
Ready · interact with <mth-image>, or toggle Theme, Direction (LTR/RTL), or props above.

Multi-Framework Playground & Snippets

<script type="module" src="@methane-ui/ui/image"></script>
<mth-image fit="cover" loading="lazy"></mth-image>

Properties & Attributes

PropertyAttributeTypeDefaultDescription
srcsrcstring""Primary image URL (validated against safe HTTP(S)/relative protocols).
altaltstring""Alternative text describing the image.
fallbackSrcfallback-srcstring""Optional backup URL loaded if the primary src fails.
aspectRatioaspect-ratiostring""CSS aspect-ratio applied to the image container (e.g. 16/9).
fitfit'cover' | 'contain' | 'fill' | 'none' | 'scale-down'"cover"Object-fit mode for the rendered image.
loadingloading'lazy' | 'eager'"lazy"Native browser loading strategy (lazy or eager).
decodingdecoding'async' | 'sync' | 'auto'"async"Image decoding hint (async, sync, or auto).
roundedroundedbooleanfalseApplies rounded corner radius tokens to the container.

Events

EventDetail TypeDescription
mth-load{ src: string }Fired when the active image finishes loading.
mth-error{ src: string }Fired when the image fails to load or src is rejected as unsafe.

Accessibility Checklist

CategoryRequirementVerified By
ariaAll aria-* IDREFs resolve within the same DOM root (ADR-003).scanSameRootAria
focusFocus ownership matches focusModel="none".lint-plugin & spec-compiler
contrastRenders legible borders, focus outlines, and selection indicators under forced-colors: active.Playwright forced-colors matrix
statesExposes ElementInternals CustomStateSet flags: :state(loading), :state(loaded), :state(error).Conformance suite
i18nRoutes 2 UI/ARIA strings through @methane-ui/core i18n catalog.Locale context test