160 lines
3.9 KiB
Markdown
160 lines
3.9 KiB
Markdown
# Image
|
|
|
|
An image element with an optional fallback for loading and error status.
|
|
|
|
## Import
|
|
|
|
```
|
|
Copyts
|
|
import { Image } from "@kobalte/core/image";
|
|
// or
|
|
import { Root, Img, ... } from "@kobalte/core/image";
|
|
// or (deprecated)
|
|
import { Image } from "@kobalte/core";
|
|
```
|
|
|
|
```
|
|
Copyts
|
|
import { Image } from "@kobalte/core/image";
|
|
// or
|
|
import { Root, Img, ... } from "@kobalte/core/image";
|
|
// or (deprecated)
|
|
import { Image } from "@kobalte/core";
|
|
```
|
|
|
|
## Features
|
|
|
|
- Automatic and manual control over when the image renders.
|
|
- Fallback part accepts any children.
|
|
- Optionally delay fallback rendering to avoid content flashing.
|
|
|
|
## Anatomy
|
|
|
|
The image consists of:
|
|
|
|
- **Image:** The root container for an image.
|
|
- **Image.Img:** The image to render. By default, it will only render when it has loaded.
|
|
- **Image.Fallback:** An element that renders when the image hasn't loaded. This means whilst it's loading, or if there was an error.
|
|
|
|
```
|
|
Copytsx
|
|
<Image>
|
|
<Image.Img />
|
|
<Image.Fallback />
|
|
</Image>
|
|
```
|
|
|
|
```
|
|
Copytsx
|
|
<Image>
|
|
<Image.Img />
|
|
<Image.Fallback />
|
|
</Image>
|
|
```
|
|
|
|
## Example
|
|
|
|
MD
|
|
|
|
index.tsxstyle.css
|
|
|
|
```
|
|
Copytsx
|
|
import { Image } from "@kobalte/core/image";
|
|
import "./style.css";
|
|
|
|
function App() {
|
|
return (
|
|
<>
|
|
<Image fallbackDelay={600} class="image">
|
|
<Image.Img
|
|
class="image__img"
|
|
src="https://randomuser.me/api/portraits/women/44.jpg"
|
|
alt="Nicole Steeves"
|
|
/>
|
|
<Image.Fallback class="image__fallback">NS</Image.Fallback>
|
|
</Image>
|
|
<Image class="image">
|
|
<Image.Fallback class="image__fallback">MD</Image.Fallback>
|
|
</Image>
|
|
</>
|
|
);
|
|
}
|
|
```
|
|
|
|
```
|
|
Copytsx
|
|
import { Image } from "@kobalte/core/image";
|
|
import "./style.css";
|
|
|
|
function App() {
|
|
return (
|
|
<>
|
|
<Image fallbackDelay={600} class="image">
|
|
<Image.Img
|
|
class="image__img"
|
|
src="https://randomuser.me/api/portraits/women/44.jpg"
|
|
alt="Nicole Steeves"
|
|
/>
|
|
<Image.Fallback class="image__fallback">NS</Image.Fallback>
|
|
</Image>
|
|
<Image class="image">
|
|
<Image.Fallback class="image__fallback">MD</Image.Fallback>
|
|
</Image>
|
|
</>
|
|
);
|
|
}
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Avoid flash during loading
|
|
|
|
By default `Image.Fallback` will render when the image hasn't loaded. This means whilst it's loading, or if there was an error.
|
|
|
|
If you notice a flash during loading, use the `fallbackDelay` prop to delay its rendering, so it only renders for those with slower internet connections.
|
|
|
|
```
|
|
Copytsx
|
|
<Image fallbackDelay={600} class="image">
|
|
<Image.Img
|
|
class="image__img"
|
|
src="https://randomuser.me/api/portraits/women/44.jpg"
|
|
alt="Nicole Steeves"
|
|
/>
|
|
<Image.Fallback class="image__fallback">NS</Image.Fallback>
|
|
</Image>
|
|
```
|
|
|
|
```
|
|
Copytsx
|
|
<Image fallbackDelay={600} class="image">
|
|
<Image.Img
|
|
class="image__img"
|
|
src="https://randomuser.me/api/portraits/women/44.jpg"
|
|
alt="Nicole Steeves"
|
|
/>
|
|
<Image.Fallback class="image__fallback">NS</Image.Fallback>
|
|
</Image>
|
|
```
|
|
|
|
## API Reference
|
|
|
|
### Image
|
|
|
|
`Image` is equivalent to the `Root` import from `@kobalte/core/image` (and deprecated `Image.Root`).
|
|
|
|
| Prop | Description |
|
|
| --- | --- |
|
|
| fallbackDelay | `number`<br> The delay (in ms) before displaying the image fallback. Useful if you notice a flash during loading for delaying rendering, so it only appears for those with slower internet connections. |
|
|
| onLoadingStatusChange | `(status: "idle" | "loading" | "loaded" | "error") => void`<br> A callback providing information about the loading status of the image. This is useful in case you want to control more precisely what to render as the image is loading. |
|
|
|
|
## Rendered elements
|
|
|
|
| Component | Default rendered element |
|
|
| --- | --- |
|
|
| `Image` | `span` |
|
|
| `Image.Img` | `img` |
|
|
| `Image.Fallback` | `span` |
|
|
|
|
Previous[←Hover Card](https://kobalte.dev/docs/core/components/hover-card)Next[Link→](https://kobalte.dev/docs/core/components/link) |