Image

A versatile image component with responsive features, lazy loading, aspect ratios, object fit, rounded corners, overlays, zoom, and more. Includes several helper subcomponents for advanced use cases.

---

Import

import { Image } from '@odyssee/components';
// Helpers (optional)
import { ImageZoom, ImageOverlay, BackgroundImage, AvatarImage } from '@odyssee/components';

---

Basic Usage

Code Éditable

Résultat

---

Object Fit

Code Éditable

Résultat

---

Rounded Corners

Code Éditable

Résultat

---

Aspect Ratios

Code Éditable

Résultat

---

Lazy Loading

Code Éditable

Résultat

---

Image with Zoom on Hover

Code Éditable

Résultat

---

Image with Overlay Content

Code Éditable

Résultat

---

Background Image

Code Éditable

Résultat

---

Avatar Image

Code Éditable

Résultat

---

Props

Name	Type	Default	Description
src	string	—	Image source URL (required)
alt	string	—	Alt text for accessibility (required)
width	string | number	—	Image width (e.g. '96', 'full', 'auto')
height	string | number	—	Image height (e.g. '96', 'full', 'auto')
objectFit	'contain' | 'cover' | 'fill' | 'none' | 'scale-down'	—	Object fit behavior
objectPosition	'center' | 'top' | 'right' | 'bottom' | 'left' ...	—	Object position
rounded	'none' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | 'full'	'none'	Border radius
loading	'eager' | 'lazy'	'lazy'	Loading strategy
display	'block' | 'inline' | 'inline-block'	'block'	Display type
aspectRatio	'square' | 'video' | '4/3' | '16/9' | '21/9' | 'auto'	—	Aspect ratio
onLoad	() => void	—	Callback on image load
onError	() => void	—	Callback on image error
fallbackSrc	string	—	Fallback image source on error
className	string	—	Additional CSS classes
id	string	auto	DOM id (auto-generated if not provided)
style	string	—	Inline styles
...rest	any	—	Other props are spread to the root <img>

ImageZoom Props

All Image props, plus:

Name	Type	Default	Description
zoomScale	number	105	Zoom scale on hover (percent)
duration	number	500	Transition duration in ms

ImageOverlay Props

All Image props (except children), plus:

Name	Type	Default	Description
children	Pulse.JSX.Element | ... | string	—	Overlay content
overlayPosition	'top' | 'bottom' | 'center' | 'full'	'bottom'	Overlay position
hoverShadow	boolean	true	Enable hover shadow
href	string	—	Link URL (renders as <a> if provided)

BackgroundImage Props

Name	Type	Default	Description
src	string	—	Background image URL
size	'auto' | 'cover' | 'contain'	'cover'	Background size
position	'center' | 'top' | 'right' ...	'center'	Background position
repeat	'repeat' | 'no-repeat' | 'repeat-x' | 'repeat-y'	'no-repeat'	Background repeat
attachment	'fixed' | 'local' | 'scroll'	'scroll'	Background attachment
children	Pulse.JSX.Element | ... | string	—	Content to overlay
minHeight	string	'min-h-60'	Minimum height
rounded	'none' | 'sm' | 'md' | 'lg' ...	'none'	Border radius
className	string	—	Additional CSS classes
id	string	—	DOM id
style	string	—	Inline styles

AvatarImage Props

All Image props (except rounded), plus:

Name	Type	Default	Description
size	'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'	'md'	Avatar size (applies width/height)

---

Accessibility

• Always provide a meaningful alt attribute for images.
• Uses semantic <img> or <div> containers.
• Overlay and background images should ensure sufficient color contrast for text.
• Avoid using images as the only means of conveying important information.

---

Best Practices

• Use objectFit and aspectRatio for responsive, consistent layouts.
• Prefer loading='lazy' for images below the fold.
• Use ImageOverlay for captions or actions over images.
• Use AvatarImage for user profile pictures.
• Test images for accessibility (alt text, contrast, keyboard focus for overlays).
• Use fallbackSrc for robust error handling.

---

Subcomponents & Helpers

• ImageZoom: Image with zoom effect on hover.
• ImageOverlay: Image with overlay content and optional link.
• BackgroundImage: Div with background image and overlay content.
• AvatarImage: Circular image for avatars.

---