Image
Classless responsive image with optional shape, fit, and emphasis values. A plain <img> is responsive by default; the .image mirror class is available for non-<img> elements or when an explicit hook is needed. Composable values control the shape (rounded, circular), the fit behavior (cover, contain, fill), and the emphasis (subtle/neutral/accent, where accent renders a decorative frame).
Usage
When to use
- Embedding any raster or vector image inside content
- When a responsive, fluid image is needed without extra wrapper markup
- Applying a consistent rounded, circular, or framed-accent treatment to an image across the site
When not to use
- For images that need a caption - use the
figurecomponent instead - For decorative background imagery driven by layout - use a CSS
background-imageon the container - For logos - use the
logocomponent so responsive sources and dark-mode swaps are handled consistently
Do
- Provide a meaningful
altattribute on every<img> - Use
alt=""for purely decorative images so screen readers skip them - Add
loading="lazy"on below-the-fold images for performance
Don't
- Embed text inside images - use real text alongside or a
<figure>with<figcaption> - Combine shape and emphasis values that visually conflict (e.g.
.circlewith a heavy.accentframe)
API
Props
| Prop | Type | Default | Description |
|---|---|---|---|
src | string | - | Image URL. |
alt | string | - | Alternative text. Use an empty string for purely decorative images. |
loading | Enum: lazy, eager | - | Browser loading strategy. Omit for default browser behavior. |
classes | array | - | Additional CSS class words merged into the root element. |
attributes | object | - | Additional HTML attributes spread on the root element. |
Classes
| Class | Capability | Default | Description |
|---|---|---|---|
.subtle | Emphasis | - | Lower emphasis; a muted, quieter weight. |
.neutral | Emphasis | Yes | Default emphasis; the standard weight at balanced contrast. |
.accent | Emphasis | - | Higher emphasis; a stronger, louder weight. |
.sm | Size | - | Small. |
.md | Size | Yes | Medium. |
.lg | Size | - | Large. |
.rounded | Shape | - | Rounded corners. |
.square | Shape | - | Sharp corners. |
.pill | Shape | - | Fully rounded ends. |
.circle | Shape | - | Perfect circle. |
.cover | Fit | - | Content fills the box, cropping overflow (object-fit: cover). |
.contain | Fit | - | Content scales within the box preserving aspect ratio (object-fit: contain). |
.fill | Fit | - | Content stretches to fill the box, may distort (object-fit: fill). |
Examples
Lazy loading
loading="lazy" demonstration.
Shapes
Every shape value side by side, each setting the corner geometry of the same photograph.
Fit
Every fit value in a fixed frame, so the difference between filling the box and fitting inside it is visible.
Accessibility
- WCAG 2.2 AA
- Every
<img>has analtattribute. - Decorative images use
alt=""so they are ignored by assistive tech. - Text embedded in images is avoided in favor of real text.
- Color and shape alone never convey meaning - captions live in
<figure>.