Skip to content
THE COMPONENT LIBRARY
Skip to content

Component reference

ThemeBuilder

An appearance panel whose selection belongs to the application.

Preview

Live preview

Changes apply to this preview only.

defaultlightradius: mediumdensity: comfortable#5B55E7

Build your theme

Default · Light
Style preset
Color mode
#5B55E7
Radius
Density
Live previewTokens applied

A small surface, every token.

Buttons, fields and badges follow the palette, radius and density you pick.

Width adapts to the available space

More examples

Different configurations and compositions using the real Pimolu API. Each preview runs independently and follows the site appearance.

Custom preview

Supply any ReactNode as preview. It renders inside the themed preview scope, so Pimolu components pick up the selected preset, colour mode, radius, density and brand colour.

Open preview

Integration

ThemeBuilder stays a controlled view or owns its fallback state. Wire the same values into PimoluProvider when the choice must reach the rest of the application.

Open preview

Example: documentation appearance panel

An uncontrolled builder is useful for a quick demo; pass defaultValue to start on a specific preset.

Open preview

Usage

ThemeBuilder reports a choice; connect it to your application's appearance state deliberately.

API reference

Generated from the public TypeScript declarations. Native HTML attributes are inherited where the component extends them; this reference includes Pimolu props and selected common native attributes.

PimoluThemeBuilderPreset

Type source
PimoluThemeBuilderPreset public API
NameTypeDefaultDescription
idRequiredstring—Stable identifier passed to `onValueChange`.
labelRequiredstring—Visible preset name.
descriptionstring | undefined—Optional supporting copy under the name.
colorsreadonly string[] | undefined—Swatches shown on the card, for example a palette preview.
idRequired

string

No default extracted.

Stable identifier passed to `onValueChange`.

labelRequired

string

No default extracted.

Visible preset name.

description

string | undefined

No default extracted.

Optional supporting copy under the name.

colors

readonly string[] | undefined

No default extracted.

Swatches shown on the card, for example a palette preview.

PimoluThemeBuilderProps

Type source
PimoluThemeBuilderProps public API
NameTypeDefaultDescription
presetsRequiredreadonly PimoluThemeBuilderPreset[]—Preset cards, in display order.
valuestring | undefined—Controlled preset id.
defaultValuestring | undefinedthe first presetInitial preset id when uncontrolled. Defaults to the first preset.
onValueChange((presetId: string) => void) | undefined—Called with the next preset id.
themePimoluThemeBuilderTheme | undefined"light" when uncontrolledControlled colour mode. Defaults to "light" when uncontrolled.
onThemeChange((theme: PimoluThemeBuilderTheme) => void) | undefined—Called with the next colour mode.
brandColorstring | undefined#5B55E7 when uncontrolledControlled brand colour. Defaults to #5B55E7 when uncontrolled.
onBrandColorChange((color: string) => void) | undefined—Called with the colour emitted by the native colour input.
radiusstring | undefined"medium"Controlled radius dimension. Defaults to "medium".
onRadiusChange((radius: string) => void) | undefined—Called with the next radius dimension.
densitystring | undefined"comfortable"Controlled density dimension. Defaults to "comfortable".
onDensityChange((density: string) => void) | undefined—Called with the next density dimension.
previewReactNode—Custom preview surface. A small component sample is rendered without it.
titlestring | undefined—Optional heading for the builder.
classNamestring | undefined—Standard React/HTML attribute.
styleCSSProperties | undefined—Standard React/HTML attribute.
aria-labelstring | undefined—Defines a string value that labels the current element.
childrenReactNode—Standard React/HTML attribute.
onClickMouseEventHandler<HTMLDivElement> | undefined—Standard React/HTML attribute.
presetsRequired

readonly PimoluThemeBuilderPreset[]

No default extracted.

Preset cards, in display order.

value

string | undefined

No default extracted.

Controlled preset id.

defaultValue

string | undefined

Default: the first preset

Initial preset id when uncontrolled. Defaults to the first preset.

onValueChange

((presetId: string) => void) | undefined

No default extracted.

Called with the next preset id.

theme

PimoluThemeBuilderTheme | undefined

Default: "light" when uncontrolled

Controlled colour mode. Defaults to "light" when uncontrolled.

onThemeChange

((theme: PimoluThemeBuilderTheme) => void) | undefined

No default extracted.

Called with the next colour mode.

brandColor

string | undefined

Default: #5B55E7 when uncontrolled

Controlled brand colour. Defaults to #5B55E7 when uncontrolled.

onBrandColorChange

((color: string) => void) | undefined

No default extracted.

Called with the colour emitted by the native colour input.

radius

string | undefined

Default: "medium"

Controlled radius dimension. Defaults to "medium".

onRadiusChange

((radius: string) => void) | undefined

No default extracted.

Called with the next radius dimension.

density

string | undefined

Default: "comfortable"

Controlled density dimension. Defaults to "comfortable".

onDensityChange

((density: string) => void) | undefined

No default extracted.

Called with the next density dimension.

preview

ReactNode

No default extracted.

Custom preview surface. A small component sample is rendered without it.

title

string | undefined

No default extracted.

Optional heading for the builder.

className

string | undefined

No default extracted.

Standard React/HTML attribute.

style

CSSProperties | undefined

No default extracted.

Standard React/HTML attribute.

aria-label

string | undefined

No default extracted.

Defines a string value that labels the current element.

children

ReactNode

No default extracted.

Standard React/HTML attribute.

onClick

MouseEventHandler<HTMLDivElement> | undefined

No default extracted.

Standard React/HTML attribute.

Accessibility

  • Keep preset names visible, and check the contrast of the resulting theme.
Read the accessibility guide →