Image
An accessible <img> wrapper that enforces meaningful alt text at compile time and at runtime in development.
npx artui@latest add imagePlayground
Usage
Meaningful image
import { Image } from '@artui/registry';
<Image
src="/team-photo.jpg"
alt="The engineering team gathered around a whiteboard during a sprint planning session"
width={800}
height={450}
/>Write alt text for what the image communicates in context, not what it depicts.
Decorative image
<Image src="/divider-wave.svg" decorative />When an image is purely visual, pass decorative. The component renders alt="" and role="presentation" so screen readers skip the element.
Above-the-fold image
<Image
src="/hero.jpg"
alt="A developer reviewing a pull request on a large monitor"
width={1440}
height={600}
loading="eager"
/>loading defaults to "lazy". Override with "eager" for images visible on first paint.
API
| Prop | Type | Default | Description |
|---|---|---|---|
| altrequired | string | none | Description of what the image communicates. Required unless `decorative` is set. Rejects placeholder strings like "image" or "photo" at compile time. |
| decorative | true | none | Marks the image as purely decorative. Renders an empty alt and role="presentation". Mutually exclusive with `alt`. |
| src | string | none | The image URL. Standard `<img>` attribute, forwarded as-is along with any other `ImgHTMLAttributes`. |
| loading | "lazy" | "eager" | none | Native browser loading hint. Defaults to "lazy" when omitted, so below-the-fold images defer loading without extra configuration. |
Accessibility
| Criterion | Name | How the component satisfies it |
|---|---|---|
| 1.1.1(A) | Non-text Content | Every <img> has either a meaningful text alternative or is explicitly marked decorative. Those are the two valid choices under WCAG Non-text Content. |
| 4.1.2(A) | Name, Role, Value | Decorative images are exposed with role="presentation" so assistive technology can skip them. |
Do
Describe what the image communicates in context
<Image
src="/ceo-headshot.jpg"
alt="Maria Chen, Chief Executive Officer, smiling in a grey blazer"
/>Mark decorative images with decorative
<Image src="/background-pattern.svg" decorative />The decorative prop makes intent explicit and renders the correct attributes (alt="", role="presentation") without relying on the caller to remember both.
Don't
Use placeholder strings
<Image src="/ceo-headshot.jpg" alt="photo" /> {/* type error */}Placeholder strings like "photo" or "image" are rejected at compile time. They tell screen reader users nothing the browser has not already communicated.
Pass an empty alt without decorative
<Image src="/background-pattern.svg" alt="" /> {/* runtime overlay in dev */}An empty alt without decorative is ambiguous. The component flags it in development so the distinction is always deliberate.