Image

Installation

$npx litefy@latest add image

$pnpm dlx litefy@latest add image

$yarn dlx litefy@latest add image

$bun --bun litefy@latest add image

Usage

Basic Usage

Preloads the image and manages the loading state, rendering the image on success.

"use client";import {  Image } from "@/ui";export default function ImageLoadingDemo() {  return (        <Image        src="https://picsum.photos/seed/1/1200/800"        alt="Random landscape image"        className={"w-160 h-80 border"}      />  );}

Loading States

Customize the loading placeholder via loadingNode, commonly used for blurred-thumbnail progressive loading; shows fallback on failure.

"use client";import { Image } from "@/ui";export default function ImageLoadingDemo() {  return (    <Image      src="https://picsum.photos/seed/3/1200/800"      alt="Random image"      className={"w-160 h-80 border"}      loadingNode={        <div className="relative size-full bg-neutral animate-pulse">          <img            src="https://picsum.photos/seed/3/100/100"            alt=""            className="absolute inset-0 w-full h-full object-cover blur-sm scale-110"          />        </div>      }    />  );}

Custom

Build a fully custom image using the low-level atomic components ImageRoot and ImageImage.

"use client";import { ImageRoot, ImageImage } from "@/ui";export default function ImageAtomicDemo() {  return (    <ImageRoot className="w-40 h-40 rounded-md overflow-hidden">      <ImageImage        src="https://picsum.photos/seed/img1/320/320"        alt="demo image"      />    </ImageRoot>  );}

API Reference

High-level Components

Ready-to-use composite components.

Image

An image component with preload state management; the outer container has built-in relative and overflow-hidden styles.

Prop	Type	Default	Description
`src`	`string`	- (required)	Image source URL
`alt`	`string`	-	Alternative text for the image
`fallback`	`React.ReactNode`	-	Custom fallback element shown when the image fails to load
`loadingNode`	`React.ReactNode`	-	Placeholder element shown while loading, commonly used for progressive blurred thumbnails
`className`	`ClassNameValue`	-	Custom classes, applied to the root container
`style`	`React.CSSProperties`	-	Inline styles, applied to the root container
`classNames`	`{ image?: ClassNameValue }`	-	Custom classes for the image
`styles`	`{ image?: React.CSSProperties }`	-	Inline styles for the image

Composable Components

ImageRoot

Outer container with built-in relative and overflow-hidden.

Prop	Type	Default	Description
`className`	`ClassNameValue`	-	Custom class name
`...props`	`React.ComponentProps<"div">`	-	Supports all native div props

ImageImage

The image element with built-in size-full, object-cover, loading="lazy" and decoding="async".

Prop	Type	Default	Description
`className`	`ClassNameValue`	-	Custom class name
`...props`	`React.ComponentProps<"img">`	-	Supports all native img props

Image

On this page