# Image
Displays an image. Renders a native `img`, defaults to `object-fit: cover`, and accepts every style prop.
Nothing extra happens by default. Lazy loading, a loading placeholder and an error placeholder are all opt-in.
Group: Basics
## Import
```tsx
import { Image } from "@indoku/ui"
```
## Examples
### Basic
```tsx
const art = (hue: number, w = 600, h = 400) =>
`data:image/svg+xml;utf8,${encodeURIComponent(``)}`
function ImageBasic() {
return
}
```
### Height
Use the `height` prop to change the height of the image.
```tsx
const art = (hue: number, w = 600, h = 400) =>
`data:image/svg+xml;utf8,${encodeURIComponent(``)}`
function ImageWithHeight() {
return
}
```
### Circular
Combine `boxSize` and `borderRadius="full"` for a round image.
```tsx
const art = (hue: number, w = 600, h = 400) =>
`data:image/svg+xml;utf8,${encodeURIComponent(``)}`
function ImageCircular() {
return
}
```
### Aspect ratio
Use the `aspectRatio` prop to change the aspect ratio of the image.
```tsx
const art = (hue: number, w = 600, h = 400) =>
`data:image/svg+xml;utf8,${encodeURIComponent(``)}`
function ImageWithAspectRatio() {
return
}
```
### Fit
By default the image applies `object-fit: cover`. Use `fit` to change it.
```tsx
const art = (hue: number, w = 600, h = 400) =>
`data:image/svg+xml;utf8,${encodeURIComponent(``)}`
function ImageWithFit() {
return (
{(["cover", "contain", "fill"] as const).map((fit) => (
{fit}
))}
)
}
```
### Align
Use `align` to set `object-position` when the image is cropped.
```tsx
const art = (hue: number, w = 600, h = 400) =>
`data:image/svg+xml;utf8,${encodeURIComponent(``)}`
function ImageWithAlign() {
return (
{(["top", "center", "bottom"] as const).map((align) => (
{align}
))}
)
}
```
### HTML width and height
`htmlWidth` and `htmlHeight` set the native `width` and `height` attributes, while `width` and `height` are style props.
```tsx
const art = (hue: number, w = 600, h = 400) =>
`data:image/svg+xml;utf8,${encodeURIComponent(``)}`
function ImageWithHtmlSize() {
return
}
```
### As child
Use `asChild` to apply the image styles to a single child, such as a framework image component.
```tsx
const art = (hue: number, w = 600, h = 400) =>
`data:image/svg+xml;utf8,${encodeURIComponent(``)}`
function ImageAsChild() {
return (
)
}
```
### Lazy loading
Not lazy by default. Add the native `loading="lazy"` so the browser downloads the image only when it is near the viewport.
```tsx
const art = (hue: number, w = 600, h = 400) =>
`data:image/svg+xml;utf8,${encodeURIComponent(``)}`
function ImageLazy() {
return
}
```
### Loading placeholder
`fallback` is shown until the image has loaded. Give the image a size (`w`/`h`, `boxSize` or `aspectRatio`) so the placeholder has room. This demo delays the source to simulate a slow network.
```tsx
const art = (hue: number, w = 600, h = 400) =>
`data:image/svg+xml;utf8,${encodeURIComponent(``)}`
function ImageWithFallback() {
const [src, setSrc] = React.useState()
React.useEffect(() => {
if (src) return
const timer = setTimeout(() => setSrc(art(170)), 1500)
return () => clearTimeout(timer)
}, [src])
return (
} />
)
}
```
### Error placeholder
When the image fails to load (404, bad URL, blocked), a built-in icon placeholder is shown. Replace it with `errorFallback`. Using `errorFallback` alone adds no loading placeholder.
```tsx
function ImageWithError() {
return (
} />
default error iconNo preview} />
custom errorFallback
)
}
```
### Responsive sources
Native `srcSet` and `sizes` let the browser pick the smallest file that fits the layout.
```tsx
const art = (hue: number, w = 600, h = 400) =>
`data:image/svg+xml;utf8,${encodeURIComponent(``)}`
function ImageResponsive() {
return (
)
}
```
## Props
### Image
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `fit` | `CSSProperties['objectFit']` | `'cover'` | Maps to `object-fit`. |
| `align` | `CSSProperties['objectPosition']` | | Maps to `object-position`. |
| `htmlWidth` | `string \| number` | | Native `width` attribute. Use `width` for the CSS property. |
| `htmlHeight` | `string \| number` | | Native `height` attribute. Use `height` for the CSS property. |
| `asChild` | `boolean` | `false` | Render the single child element with the image props and styles instead of an `img`. `fallback` and `errorFallback` are ignored. |
| `fallback` | `ReactNode` | | Shown until the image has loaded. Setting it wraps the image in a frame. |
| `errorFallback` | `ReactNode` | | Replaces the built-in error icon. Setting it (or `fallback`) enables the error placeholder. |
`*` = required. Style props and HTML attributes are accepted too.
## Accessibility
- Always set `alt`. Use `alt=""` for purely decorative images.
- The loading placeholder is hidden from assistive tech. The error placeholder is exposed as an image labelled with `alt`.
- Set `htmlWidth` and `htmlHeight` (or `aspectRatio`) to reserve space and avoid layout shift while loading.
## Notes
- All native `img` attributes are forwarded, including `loading`, `decoding`, `srcSet`, `sizes`, `onLoad` and `onError`.
- With `fallback` or `errorFallback`, size and style props apply to a wrapping `span` frame, and `fit`, `ref` and native attributes stay on the `img`. Without them there is no wrapper.
- Image optimization (smaller files in WebP or AVIF) happens at build time or on a CDN, not in this component. Use `srcSet` and `sizes` for responsive files, and wrap with `` and `` to offer modern formats with a fallback.
- The Provider preflight already sets `display: block`, `max-width: 100%` and `height: auto` on images.
## See also
- Aspect Ratio: https://ui.indoku.org/docs/aspect-ratio
- Avatar: https://ui.indoku.org/docs/avatar
- Skeleton: https://ui.indoku.org/docs/skeleton