Image Component
The Image component provides a responsive and stylable wrapper for images. Supports aspect ratios, overlays, fallback content, lazy loading, click interactions, shadows, borders, and custom styles — all with full TypeScript support.
Import Component From Library
1import { Image } from "@neuctra/ui";Basic Usage Code
Start with a simple image. The component provides responsive and stylable image support with overlays, aspect ratios, and interactions.
1import { Image } from '@neuctra/ui';
2
3function BasicExample() {
4 return (
5 <Image
6 src="https://via.placeholder.com/300"
7 alt="Sample Image"
8 width={300}
9 height={200}
10 className="rounded-lg"
11 />
12 );
13}Basic Example
Advanced Usage
Props Table
All available props for the Image component.
| Prop | Type | Default | Description |
|---|---|---|---|
| src | string | — | Image source URL. |
| alt | string | "" | Alternative text for accessibility. |
| title | string | — | Tooltip text. |
| width | Responsive<number | string> | "100%" | Width of the image (responsive supported). |
| height | Responsive<number | string> | — | Height of the image. |
| aspectRatio | number | — | Maintain a fixed width/height ratio. |
| radius | number | string | — | Border radius for wrapper. |
| border | string | — | Custom border CSS value. |
| shadow | boolean | — | Enable shadow around image. |
| opacity | number | 1 | Opacity of the image. |
| objectFit | React.CSSProperties["objectFit"] | "cover" | Controls how the image fits. |
| overlay | ReactNode | — | Content displayed on top of the image. |
| overlayColor | string | "color-mix(in srgb, var(--background) 60%, transparent)" | Overlay background color. |
| clickable | boolean | false | Makes image interactive (button-like). |
| onClick | (e: MouseEvent) => void | — | Click event handler. |
| fallback | ReactNode | — | Content shown when no image is available (defaults to "No Image"). |
| loading | "lazy" | "eager" | "lazy" | Image loading behavior. |
| className | string | — | Wrapper container classes. |
| imageClassName | string | — | Classes for the <img> element. |
| overlayClassName | string | — | Classes for overlay container. |
| fallbackClassName | string | — | Classes for fallback container. |
| style | React.CSSProperties | — | Wrapper inline styles. |
| imageStyle | React.CSSProperties | — | Inline styles for image element. |
| overlayStyle | React.CSSProperties | — | Inline styles for overlay. |
| fallbackStyle | React.CSSProperties | — | Inline styles for fallback container. |
| ...rest | HTMLDivElement attributes | — | All native div props (id, data-*, aria-*, etc). |
Common Mistakes
<Image width="50px" height="50px" />Use responsive numbers or percentages, not raw CSS strings for better consistency.
<Image src="" />Always provide src or a fallback to avoid empty placeholders.
<Image className="rounded shadow" />Use className or style for visual adjustments.
Pro Tips
- Use aspectRatio to maintain consistent layouts.
- Apply radius and shadow for card-like styling.
- Use overlay for captions, badges, or hover effects.
- Enable clickable with keyboard accessibility (Enter / Space).
- Use fallback to handle missing images gracefully.
- Prefer lazy loading for performance on large image grids.
Frequently Asked Questions
How do I install and import the Image component?
Install the @neuctra/ui package, then import it with: import { Image } from "@neuctra/ui";
Can I customize the Image component's appearance?
Yes. Image accepts a className prop for custom Tailwind CSS classes, so you can adjust spacing, layout, and styling without overriding the component internals.
Is the Image component accessible?
Image is built with semantic HTML and standard ARIA attributes, and supports keyboard navigation and focus states out of the box, so it works well with screen readers and keyboard-only users.