Shader Preset Picker

Runtime gallery of shader presets — click to select. Powered by the same preset registry as <ThreeScene>.

Installation

import { ShaderPresetPicker } from "@gradeui/ui"

Picker + live preview

Hyperspace

Hyperspacespace

Filter by tag

Every preset declares semantic tags ("space", "retro", "motion", "hero", etc.) — filter to a subset for specialised pickers.

Hyperspace

Hyperspacespace

Props

Prop	Type	Default	Description
value	string	-	Currently selected preset id (controlled).
onChange	(id: string) => void	-	Called when the user clicks a preset card.
filterTags	string[]	-	Only show presets that match at least one tag.
live	"never" \| "hover" \| "always"	"hover"	Thumbnail render mode — see Shader Preset Preview.
postPreset	string	-	Shared post-FX preset applied to every thumbnail.
palette	Partial<Palette>	-	Shared palette applied to every thumbnail.
columns	2 \| 3 \| 4	3	Grid columns at md+ breakpoint.

TODO (phase 2)

A static docs-site catalogue page — the shadcn-blocks model, listing every preset with copy-paste code — is planned separately from this runtime picker.

Sidecar

The Markdown sidecar Studio (and the Grade MCP server, when it ships) reads to understand this component — frontmatter, when- to-use guidance, and canonical examples. Authored once at packages/ui/components/ui/shader-preset-picker.md and shipped inside the published @gradeui/ui tarball.

---
name: ShaderPresetPicker
import: "@gradeui/ui"
props:
  - value?: string — currently selected preset id (controlled)
  - onChange?: (id: string) => void — called when the user clicks a preset card
  - filterTags?: string[] — only show presets matching at least one tag ("space" | "retro" | "motion" | "hero" | "background" …)
  - live?: "never" | "hover" | "always" (default "hover") — thumbnail render mode
  - postPreset?: string — shared post-FX preset applied to every thumbnail
  - palette?: Partial<Palette> — shared palette applied to every thumbnail
  - columns?: 2 | 3 | 4 (default 3) — grid columns at md+ breakpoint
when_to_use: Runtime gallery of shader presets — click to select. Use with ThreeScene as a controlled input so the user can pick a background shader. For a single preview card, use ShaderPresetPreview directly.
composes_with: [ShaderPresetPreview (internal), ThreeScene (the typical downstream consumer)]
aliases: [shader picker, preset picker, shader gallery, preset gallery]
notes: Powered by the same preset registry that drives `<ThreeScene preset="…" />` — adding a preset to the registry makes it appear here automatically. At time of writing only "space" is registered, so the picker renders a single card until more presets ship.
---

```jsx
const [preset, setPreset] = useState("space");

<ShaderPresetPicker value={preset} onChange={setPreset} />
<ThreeScene preset={preset} postPreset="vhs" aspect="wide" />

// Filter to a subset
<ShaderPresetPicker filterTags={["hero"]} columns={3} />
```