Theming
Three levels, from quick to complete. Try them live in the theme playground.
1. Dark, light or follow the OS
<ImageEditor theme="light" /> // 'dark' (default) · 'light' · 'auto'2. Typed overrides
<ImageEditor theme="light" themeOverrides={{ accent: '#155e75', radius: '12px' }} />| Key | Sets |
|---|---|
accent, accentHover, accentContrast, accentText | Primary buttons, focus, slider fill; text on and in accent colour |
bg, stage | Editor background; behind the photo |
surface1, surface2, surface3 | Bars; hover and inputs; pressed and popovers |
text, textMuted, border | Text and hairlines |
fontFamily | The editor's font (default: your page's) |
radius | Base corner radius; small and large radii follow |
Pick an accent with enough contrast against the surfaces (4.5:1 for text) — accentText lets text
use a lighter or darker shade than buttons.
3. CSS variables
Every colour, size and duration is a CSS variable on .iu-root. Setting them is the way to
restyle the editor, and it always works:
.my-editor .iu-root {
--iu-accent: #155e75;
--iu-surface-1: #0f172a;
--iu-radius-md: 4px;
}<ImageEditor className="my-editor" />The main ones:
| Variable | |
|---|---|
--iu-bg, --iu-stage | Background; behind the photo |
--iu-surface-1/2/3 | Bars; hover, inputs; pressed, popovers |
--iu-border, --iu-border-strong | Hairlines; control outlines |
--iu-text, --iu-text-muted, --iu-text-subtle | Text levels |
--iu-accent, --iu-accent-hover, --iu-accent-soft, --iu-accent-text, --iu-accent-contrast | Accent |
--iu-danger, --iu-warning | Delete, warnings |
--iu-font-family, --iu-font-mono | Fonts |
--iu-radius-sm/md/lg | Corner radii |
--iu-duration-fast/base/slow, --iu-ease | Motion (set to 0ms to turn it off) |
--iu-size-topbar, --iu-size-rail, --iu-size-controlbar | Layout sizes |
With theme="dark" or "light" the editor sets data-iu-theme on .iu-root; "auto" follows
prefers-color-scheme. Style both with .iu-root[data-iu-theme='light'] if you need to.
Your app's CSS
The editor's CSS lives in the image-ultra cascade layer, and your app's global CSS can't reach
inside it: a reset like * { padding: 0; margin: 0 } (create-next-app's default
globals.css) or Tailwind's preflight leaves the editor as it is.
To change a rule of the editor's itself, use two classes, or a cascade layer declared after
image-ultra:
.my-editor .iu-chip {
border-radius: 4px;
}With Tailwind v4 (or any CSS in layers), import @image-ultra/react/styles.css after your
own stylesheet, so the image-ultra layer comes after base.
Icons
The editor uses its own icon set (24 px grid, 1.75 px stroke). Your custom tools can use any
ComponentType<IconProps> — see Custom tools.