Skip to content
Destyler UI Destyler UI Destyler UI
Docs
Image

Image

Support for fallback text or elements when the image fails to load, or when the image is not provided.

EH
EH

Features

Install

Install the component from your command line.

Terminal window 
      
        

          

            npm
             
            install
             
            @destyler/image @destyler/vue
Terminal window 
      
        

          

            npm
             
            install
             
            @destyler/image @destyler/react
Terminal window 
      
        

          

            npm
             
            install
             
            @destyler/image @destyler/svelte
Terminal window 
      
        

          

            npm
             
            install
             
            @destyler/image @destyler/solid

Anatomy

Import all parts and piece them together.

<script setup lang="ts">
import * as image from '@destyler/image'
import { normalizeProps, useMachine } from '@destyler/vue'
import { computed, useId } from 'vue'


const [state, send] = useMachine(image.machine({ id: useId() }))


const api = computed(() => image.connect(state.value, send, normalizeProps))
</script>


<template>
  <div v-bind="api.getRootProps()">
    <img v-bind="api.getImageProps()" >
    <div v-bind="api.getFallbackProps()" ></div>
  </div>
</template>
import * as image from '@destyler/image'
import { normalizeProps, useMachine } from '@destyler/react'
import { useId } from 'react'


export default function Image() {
  const [state, send] = useMachine(image.machine({
    id: useId(),
  }))


  const api = image.connect(state, send, normalizeProps)


  return (
    <div {...api.getRootProps()}>
      <img {...api.getImageProps()}/>
      <div {...api.getFallbackProps()}></div>
    </div>
  )
}
<script lang="ts">
  import * as image from '@destyler/image'
  import { normalizeProps, useMachine } from '@destyler/svelte'


  const id = $props.id()


  const [state, send] = useMachine(image.machine({ id }))


  const api = $derived(image.connect(state, send, normalizeProps))
</script>


<div {...api.getRootProps()}>
  <img {...api.getImageProps()} />
  <div {...api.getFallbackProps()} ></div>
</div>
import * as image from '@destyler/image'
import { normalizeProps, useMachine } from '@destyler/solid'
import { createMemo, createUniqueId } from 'solid-js'


export default function Image() {
  const [state, send] = useMachine(image.machine({
    id: createUniqueId(),
  }))


  const api = createMemo(() => image.connect(state, send, normalizeProps))


  return (
    <div {...api().getRootProps()}>
      <img {...api().getImageProps()}/>
      <div {...api().getFallbackProps()} ></div>
    </div>
  )
}

Listening for loading status changes

When the image has loaded or failed to load, the onStatusChange callback is invoked.

const [state, send] = useMachine(
  avatar.machine({
    onStatusChange(details) {
      // details => { status: "error" | "loaded" }
    },
  }),
)

Styling guide

Earlier, we mentioned that each avatar part has a data-part attribute added to them to select and style them in the DOM.

[data-scope="avatar"][data-part="root"] {
  /* Styles for the root part */
}


[data-scope="avatar"][data-part="image"] {
  /* Styles for the image part */
}


[data-scope="avatar"][data-part="fallback"] {
  /* Styles for the fallback part */
}

Methods and Properties

Machine Context

The image machine exposes the following context properties:

onStatusChange
(details: StatusChangeDetails) => void
Functional called when the image loading status changes.
ids
Partial<{ root: string; image: string; fallback: string; }>
The ids of the elements in the avatar. Useful for composition.
id
string
The unique identifier of the machine.
getRootNode
() => ShadowRoot | Node | Document
A root node to correctly resolve document in custom environments. E.x.: Iframes, Electron.
dir(default: "ltr")
"ltr" | "rtl"
The document's text/writing direction.

Machine API

The image api exposes the following methods:

loaded
boolean
Whether the image is loaded.
setSrc
(src: string) => void
Function to set new src.
setLoaded
() => void
Function to set loaded state.
setError
() => void
Function to set error state.

Data Attributes

Image

attribute
description
data-scope
image
data-part
image
data-state
"visible" | "hidden"

Fallback

attribute
description
data-scope
image
data-part
fallback
data-state
"hidden" | "visible"

Hover Card

Floating Panel