Image

Props

• src: string (required) -- the image source URL
• alt: string (required) -- alternative text describing the image for screen readers and when the image fails to load
• caption: string (optional) -- when provided, wraps the image in a <figure> with a <figcaption>
• loading: "lazy" | "eager" (optional) -- controls the native browser loading behavior
• ...restProps: unknown -- additional attributes spread onto the root element

Keyboard Interactions

None -- this component is a passive content element. Images are not interactive by default.

ARIA

• alt="..." -- provides the accessible name for the image, required for all non-decorative images
• <figure> and <figcaption> -- when caption is present, these semantic HTML elements associate the caption with the image for assistive technology

When to Use

• Use when an image meets a genuine user need, such as helping users identify a health condition or understand a procedure
• Use with descriptive alt text that conveys the same information as the image
• Use with a caption (via Figure and Caption) to explain what users should conclude from the image
• Use when users with access needs like dyslexia benefit from visual content alongside text

When Not to Use

• Do not use decorative images that add no informational value -- they frustrate users, especially on transactional pages; use a CSS background image instead
• Do not use images containing embedded text -- screen readers cannot read text within images
• Do not arrange images side-by-side in a gallery layout -- stack vertically so users do not miss content
• Do not use when the information can be conveyed equally well through text alone

Headless

This headless component provides an <img> element with required alt text, optional <figure>/<figcaption> wrapping, and native loading attribute support. The consumer provides all visual styling including sizing, borders, rounded corners, and responsive behavior.

Styles

The consumer provides all CSS styling. The component renders with a .image class for targeting. No default styles are included — this is a fully headless component.

Testing

• Verify the component renders a <img> element with class image
• Verify pass-through attributes are applied

Advice

• Designers: Define consistent aspect ratios and sizing for images across the application. Provide placeholder or skeleton states for slow-loading images.
• Developers: Always write meaningful alt text that describes the image content. Use loading="lazy" for below-the-fold images to improve page performance.

Implementation Notes

• Renders a plain <img> element when no caption is provided
• Renders a <figure> with <img> and <figcaption> when a caption is provided
• The alt prop is required to enforce accessibility
• Rest props are spread onto the <img> element (no caption) or the <figure> element (with caption)
• Supports the native loading attribute for lazy/eager loading control

Related components

• image-input — a graphical submit button that displays an image <input type="image">
• image-file-input — an input for selecting image files with preview

References

• WAI Images Tutorial: https://www.w3.org/WAI/tutorials/images/
• HTML figure element: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/figure