# antuikit / Image

> Image with the preview toolbar's six icons drawn from your icon pack, and corners set on `classNames.root` carried to the hover cover.

Docs: https://antuikit.com/docs/components/image

## Install

npx antuikit@latest init
npx antuikit@latest add image

## Import

import { Image } from "@/components/ui/image";

## Demos

- [Preview](https://ui.antuikit.com/embed/image/preview.md): An `Image` opens a full-screen viewer on click, where you can zoom, rotate and flip it, and Esc closes it.
- [Corners](https://ui.antuikit.com/embed/image/shape.md): Put `rounded-lg` or `rounded-full` on `classNames.root`, so the image and its hover cover share the same corners.
- [Separate preview source](https://ui.antuikit.com/embed/image/preview-src.md): Pass `preview.src` to show a different file in the viewer, so the thumbnail stays small and the full image loads only when opened.
- [Preview off](https://ui.antuikit.com/embed/image/no-preview.md): Set `preview={false}` for a plain image with no viewer, like a logo or an avatar.
- [Controlled preview](https://ui.antuikit.com/embed/image/controlled-preview.md): Control the viewer with `preview.open` and `preview.onOpenChange`, so a button can open it instead of the thumbnail.
- [Custom mask](https://ui.antuikit.com/embed/image/mask.md): Set `preview.mask` to `{ blur: true }` to blur the page behind the open viewer, or to `false` for no backdrop at all.
- [Custom cover](https://ui.antuikit.com/embed/image/custom-cover.md): Pass a node to `preview.cover` to replace the hover overlay, like an eye glyph with a label or the glyph alone.
- [Fixed position](https://ui.antuikit.com/embed/image/fixed-position.md): Set `preview.movable` to `false` so a zoomed image stays centered and cannot be dragged.
- [Zoom limits](https://ui.antuikit.com/embed/image/zoom-limits.md): Use `scaleStep`, `minScale` and `maxScale` in `preview` to set how far each zoom goes, or `wheel: false` to zoom only with the toolbar.
- [Custom image render](https://ui.antuikit.com/embed/image/image-render.md): Use `preview.imageRender` to wrap the viewer's image, here with a download button in its top corner.
- [Custom toolbar](https://ui.antuikit.com/embed/image/custom-actions.md): Use `preview.actionsRender` to keep the toolbar but pick its buttons, here zoom and rotate plus copy link and download.
- [PreviewGroup](https://ui.antuikit.com/embed/image/preview-group.md): Wrap images in `Image.PreviewGroup` so the viewer steps through all of them with next and previous buttons.
- [PreviewGroup from one image](https://ui.antuikit.com/embed/image/preview-group-items.md): Pass `items` to `Image.PreviewGroup` so one thumbnail opens a viewer with the whole set, like a cover photo for an album.
- [Placeholder](https://ui.antuikit.com/embed/image/placeholder.md): Pass `placeholder` a `progress` object with your own `percent` to show a loading box, then render the image once it reaches 100.
- [Indeterminate placeholder](https://ui.antuikit.com/embed/image/placeholder-indeterminate.md): Set `placeholder={{ progress: true }}` for a loading box that animates without a percent, to show until you render the image.
- [Fallback](https://ui.antuikit.com/embed/image/fallback.md): Pass `fallback` an image to show when `src` fails to load, like a gray Not found tile instead of a broken image.
- [Lazy loading](https://ui.antuikit.com/embed/image/lazy.md): Set `loading="lazy"` so the browser holds back images far down the page, with a `placeholder` showing until each one arrives.
- [Photo gallery](https://ui.antuikit.com/embed/image/screenshot-gallery.md): A grid of photos in one `Image.PreviewGroup`, so any of them opens a viewer that steps through all eight.

## Rules

- antuikit components are COPIED into a project from a registry. There is no
  `antuikit` package to import components from at runtime.
- Import from `@/components/ui/image`, never from `antd`. antd stays for
  `theme`, `App`, the `message` / `notification` statics and type-only imports.
- Do not nest a bare `<ConfigProvider theme>` to re-theme a region. Use
  `<ThemeScope theme={...}>`, which also carries the cssVar key class that
  non-antd descendants inherit their tokens from.
- Colors, radii and spacing come from the token contract, not from hardcoded
  values: write `rounded-lg`, `px-xxs`, `bg-warning`, not the raw `var(--ant-*)`.
- `Image` takes every Ant Design v6 prop of the same component. The
  wrapper never narrows that surface, so anything antd documents also works here.