lottiefiles Creator Plugins UI Library
@lottiefiles/creator-plugins-ui — 25 accessible components built on Base UI + Tailwind CSS + CVA. Used in plugin UI code (src/) only, not the plugin sandbox.
Quick Setup
Full guide: references/setup-guide.md
npm install @lottiefiles/creator-plugins-ui
// src/main.tsx — import before local styles
import "@lottiefiles/creator-plugins-ui/styles.css";
Components and theme color utility classes (bg-primary, text-foreground, border-border, etc.) work with just styles.css — no Tailwind configuration needed.
If you need additional custom Tailwind classes beyond what the library provides, set up Tailwind v4:
npm install --save-dev tailwindcss @tailwindcss/vite
Add tailwindcss() to vite.config.ts plugins, create src/styles.css with @import "tailwindcss", and use @theme {} for custom colors. Do not create tailwind.config.js or postcss.config.js (v3 patterns). See references/setup-guide.md for full instructions.
Import Pattern
import { Button, Input, Select, Slider, cn } from "@lottiefiles/creator-plugins-ui";
Available Components
For props, variants, and API details, read the TypeScript types from the installed package — they include JSDoc comments, explicit union types, and default values:
node_modules/@lottiefiles/creator-plugins-ui/dist/components/*/
Components: Button, Input, Label, Select, Slider, NumberInput, DualNumberInput, Checkbox, Toggle, RadioGroup, Tabs, Dialog, Dropdown, Tooltip, SegmentedControl, SearchBar, Toast, Spinner, Separator, Card, Grid, EmptyState, Badge, AIPromptInput, ThemeProvider
Compound components (use sub-component composition): Dialog, Select, Dropdown, Tabs, Card, Tooltip, Toast, RadioGroup
Compound Component Pattern
Compound components (Dialog, Select, Dropdown, Tabs) use sub-component composition. Use render prop for polymorphic rendering (not asChild — this library uses Base UI, not Radix):
<DialogRoot>
<DialogTrigger render={<Button variant="outline" />}>Delete</DialogTrigger>
<DialogContent>
<DialogHeader>
<DialogTitle>Delete Layer?</DialogTitle>
<DialogDescription>This cannot be undone.</DialogDescription>
</DialogHeader>
<DialogFooter>
<DialogClose render={<Button variant="outline" />}>Cancel</DialogClose>
<Button variant="destructive"
</DialogFooter>
</DialogContent>
</DialogRoot>
Theming
Full guide: references/theming-guide.md
Dark mode: add class="dark" to <html> — document.documentElement.classList.add("dark").
Runtime overrides with ThemeProvider:
<ThemeProvider tokens={{ "--primary": "hsl(260 80% 55%)" }} themeName="custom">
<App />
</ThemeProvider>
Key CSS variables: --background, --foreground, --primary, --secondary, --destructive, --muted-foreground, --border, --ring.
cn() Utility
Use cn() from the library (not a local clsx) — it includes custom Tailwind merge config for theme colors and font sizes:
import { cn } from "@lottiefiles/creator-plugins-ui";
<div className={cn("p-4 text-foreground", isActive && "bg-primary")} />
Common Pitfalls
- Missing
styles.cssimport — Components render unstyled. Import@lottiefiles/creator-plugins-ui/styles.cssonce in entry file. - Using Tailwind v3 config with v4 — Do not create
tailwind.config.jsorpostcss.config.js. Tailwind v4 uses@import "tailwindcss"+@theme {}in CSS and@tailwindcss/vitefor Vite integration. - Using
asChildinstead ofrender— Base UI usesrender={<a href="/" />}, not Radix'sasChild+Slot. - Select empty string values —
""is reserved for "no selection". Use"none"or similar. - NumberInput is controlled only — Requires
value+onChange. No uncontrolled mode. - Slider value is always an array — Pass
[50]not50. Callback returns array too. - Toast requires provider —
useToast()throws outside<ToastProvider>. Wrap app root. - Dark mode class placement —
darkclass goes on<html>or parent, not on the component. - Wrong
cnimport — Usecnfrom@lottiefiles/creator-plugins-ui, not a localclsx.
Migration from Custom Components
Full before/after examples: references/setup-guide.md
- Replace
@stitches/reactstyled components with library components + Tailwind classes - Replace
@radix-ui/*imports with library components - Replace
asChildwithrenderprop - Replace
data-[state=checked]→data-[checked],data-[state=open]→data-[open], etc. - Replace inline colors with CSS variable classes (
text-foreground,bg-primary) - Replace custom
cn()/clsx()with library'scn()
Reference Guide
| Reference | Contents |
|---|---|
references/setup-guide.md |
Installation, Tailwind config, migration from Stitches/Radix, troubleshooting |
references/theming-guide.md |
CSS variables, dark mode, ThemeProvider, custom colors |