Image installs into your project as a file you own. It takes the same props as Ant Design's Image. It changes one default: a preview.actionsRender that draws the six toolbar icons from your icon pack, on Image and on Image.PreviewGroup. Your own actionsRender receives that toolbar and info.icons with the pack glyphs in place, and preview={false} still turns the viewer off.
Install
npx antuikit@latest init
npx antuikit@latest add image
The first command sets up AntuikitProvider and the theme tokens, and the second adds Image.
Import
Import from @/components/ui/image, not from antd. Once installed, the file lives in your project.
import { Image } from "@/components/ui/image"
The axes
Image has no variant props. You configure it with a URL, a node or a config object, and round its corners with a class like rounded-lg on classNames.root.
The one choice from a list is preview.cover's placement: top, bottom or center (the default), which places the hover overlay on the thumbnail.
Flags
Every switch is inside preview, which is the first of them. preview={false} turns the viewer off and removes the tab stop, and preview={true} is the default.
preview.movable and preview.wheel (both on by default) are drag to pan and wheel to zoom. Turn the wheel off where people expect it to scroll the page.
preview.focusTrap defaults to true and keeps Tab inside the open viewer. Leave it on.
preview.mask takes a boolean or { enabled, blur, closable }. The backdrop is on and closes on click by default, and the blur is off.
preview.open controls the viewer, paired with preview.onOpenChange. Pass both, or the viewer will not close.
preview.forceRender and preview.destroyOnClose were removed and do nothing. The viewer always renders once it has opened.
Slots
The props that take a node. Only placeholder is top-level, and the rest are in the preview config.
placeholder shows while the image loads. A node is replaced by the image, and { progress } shows a progress box instead of the image.
preview.cover is the hover overlay on the thumbnail, a node or { coverNode, placement }. The backdrop behind the viewer is preview.mask.
preview.closeIcon is the close icon, which AntuikitProvider sets from your icon pack.
preview.imageRender wraps the image in the open viewer and receives the current transform, for a caption, a watermark or content that is not an image.
preview.actionsRender renders the toolbar and preview.countRender the group's counter. Both receive the finished nodes, so clone and swap rather than rebuild them.
placeholder.progress.render renders the loading box, with the progress bar and the percent.
fallback is a URL, not a node, because it replaces the image's src when it fails to load. A data: URI is a safe choice, since it cannot fail itself.
Events
onError
preview.onOpenChange
preview.onTransform
Image.PreviewGroup
Part of the same import. It gives a set of images one viewer, with previous and next buttons, arrow keys and a counter. Images inside a group use the group's viewer, so the kit sets actionsRender on the group too.
The group's preview config adds current, onChange and an onOpenChange with the index. Its mask only takes the backdrop config, so a node is a type error there.
The group's next and previous arrows keep Ant Design's icons, because there is no way to replace them. Setting preview.icons or the top-level icons prop compiles but has no effect.
Styling
classNames and styles take the same keys. Use them before a descendant selector.
1
<Image
2
classNames={{
3
root: "…",
4
image: "…",
5
cover: "…",
6
placeholder: {
7
progress: "…",
8
},
9
popup: {
10
root: "…",
11
mask: "…",
12
body: "…",
13
footer: "…",
14
actions: "…",
15
close: "…",
16
},
17
}}
18
/>
A Tailwind class on one of these keys wins over the component's own styles without !important. Setting a component token's CSS variable on the root does nothing, so style the part instead.
API Reference
Image
Image's props.
PlaceholderType
The fields of the object form of placeholder.
ImageProgressConfig
The fields of the object form of placeholder.progress.
PreviewType
The fields of the object form of preview. Rows marked antuikit in the Version column are added by the kit.
Image.PreviewGroup
Image.PreviewGroup's props.
PreviewGroupType
The fields of the object form of Image.PreviewGroup's preview. Rows marked antuikit in the Version column are added by the kit.