Image

An optimized image component with responsive sizing, aspect ratio control, loading states, and fallback support.

Import

tsx

import { Image } from "asheeui";

Usage

tsx

import { Image } from "asheeui";

export default function Basic() {
	return (
		<Image
			src="https://images.unsplash.com/photo-1506744038136-46273834b3fb?w=800&h=600&fit=crop"
			alt="Description of image"
		/>
	);
}

Examples

Radius

Fit modes

Aspect ratios

With fallback

With skeleton loading

Lazy loading

Custom width and height

With custom image component

Props

Prop	Type	Default	Description
`src`	`string`	None	Image source URL
`alt`	`string`	None	Alt text for accessibility (required)
`fit`	`"cover" \| "contain" \| "fill" \| "none" \| "scale-down"`	`"cover"`*	How image fits its container
`ratio`	`"auto" \| "square" \| "video" \| "portrait"`	`"auto"`*	Aspect ratio of container
`radius`	`"none" \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| "full"`	`"md"`*	Corner rounding
`fallbackSrc`	`string`	None	Fallback image URL if primary fails
`showSkeleton`	`boolean`	`true`*	Shows loading skeleton
`loading`	`"lazy" \| "eager"`	`"lazy"`*	Loading strategy
`imageComponent`	`React.ElementType`	None	Custom image component (e.g., Next.js `Image`)
`imageProps`	`Record<string, unknown>`	None	Additional props for custom component (e.g., `{ priority: true }`)
`className`	`string`	None	Extra classes, merged with internal styles

* Falls back through Global Configuration if not set. See below.

Global Configuration

Image reads defaults from four places, in this order of precedence:

Instance prop: set directly on <Image />
Component config: components.image in your ashee.config
Theme default: defaultRadius in your ashee.config
Built-in fallback: component's internal default values

Component config

// ashee.config.ts
import type { ExternalConfig } from "asheeui";

export const config: ExternalConfig = {
  components: {
    image: {
      fit: "cover",
      ratio: "video",
      radius: "md",
      loading: "lazy",
      showSkeleton: true,
    },
  },
};

Built-in fallbacks

{
  fit: "cover",
  ratio: "auto",
  radius: "md",
  loading: "lazy",
  showSkeleton: true,
}

Accessibility

Requires alt prop for screen reader support
Skeleton loading state includes aria-hidden to prevent announcement
Supports loading attribute for native lazy loading
Handles image loading errors gracefully with fallback support
Proper image semantics with native img element

Notes

Alt Text: The alt prop is required for accessibility. Always provide meaningful alt text.
Fallback: When fallbackSrc is provided, the image will automatically switch to it if the primary source fails to load.
Skeleton: The skeleton loader is displayed until the image finishes loading. It can be disabled with showSkeleton={false}.
Custom Image Component: You can replace the native <img> with any custom image component (e.g., Next.js Image) using the imageComponent prop. All styles, skeleton, and fallback logic are preserved.
Aspect Ratio: When ratio is set to auto, the container will not enforce a specific aspect ratio.
Fit Modes: The fit prop controls how the image fills its container using CSS object-fit values.
Native Attributes: All standard img HTML attributes are supported (e.g., width, height, srcSet, sizes).