creator-plugins-ui

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Creator Plugins UI Library

Creator Plugins UI 库

@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.

@lottiefiles/creator-plugins-ui

— 基于 Base UI + Tailwind CSS + CVA 构建的 25 个无障碍组件。仅用于插件 UI 代码（

src/

），不用于插件沙箱。

Quick Setup

快速设置

Full guide:

references/setup-guide.md

bash

npm install @lottiefiles/creator-plugins-ui

typescript

// 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:

bash

npm install --save-dev tailwindcss @tailwindcss/vite

Add

tailwindcss()

vite.config.ts

plugins, create

src/styles.css

with

@import "tailwindcss"

, and use

@theme {}

for custom colors. Do not create

tailwind.config.js

postcss.config.js

(v3 patterns). See

references/setup-guide.md

for full instructions.

完整指南：

references/setup-guide.md

bash

npm install @lottiefiles/creator-plugins-ui

typescript

// src/main.tsx — import before local styles
import "@lottiefiles/creator-plugins-ui/styles.css";

组件和主题颜色实用工具类（

bg-primary

、

text-foreground

、

border-border

等）仅需

styles.css

即可使用——无需配置 Tailwind。

如果需要库中未提供的额外自定义 Tailwind 类，请配置 Tailwind v4：

bash

npm install --save-dev tailwindcss @tailwindcss/vite

在

vite.config.ts

的 plugins 中添加

tailwindcss()

，创建包含

@import "tailwindcss"

的

src/styles.css

，并使用

@theme {}

定义自定义颜色。不要创建

tailwind.config.js

或

postcss.config.js

（v3 模式）。完整说明请参阅

references/setup-guide.md

。

Import Pattern

导入模式

typescript

import { Button, Input, Select, Slider, cn } from "@lottiefiles/creator-plugins-ui";

typescript

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

有关 props、variants 和 API 的详细信息，请阅读已安装包中的 TypeScript 类型——其中包含 JSDoc 注释、显式联合类型和默认值：

node_modules/@lottiefiles/creator-plugins-ui/dist/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

复合组件（使用子组件组合方式）：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):

tsx

<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" onClick={handleDelete}>Delete</Button>
    </DialogFooter>
  </DialogContent>
</DialogRoot>

复合组件（Dialog、Select、Dropdown、Tabs）采用子组件组合方式。对于多态渲染，请使用

render

prop（不要使用

asChild

——此库使用 Base UI，而不是 Radix）：

tsx

<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" onClick={handleDelete}>Delete</Button>
    </DialogFooter>
  </DialogContent>
</DialogRoot>

Theming

主题

Full guide:

references/theming-guide.md

Dark mode: add

class="dark"

<html>

—

document.documentElement.classList.add("dark")

Runtime overrides with ThemeProvider:

tsx

<ThemeProvider tokens={{ "--primary": "hsl(260 80% 55%)" }} themeName="custom">
  <App />
</ThemeProvider>

Key CSS variables:

--background

--foreground

--primary

--secondary

--destructive

--muted-foreground

--border

--ring

完整指南：

references/theming-guide.md

暗色模式：将

class="dark"

添加到

<html>

——

document.documentElement.classList.add("dark")

。

通过 ThemeProvider 进行运行时覆盖：

tsx

<ThemeProvider tokens={{ "--primary": "hsl(260 80% 55%)" }} themeName="custom">
  <App />
</ThemeProvider>

关键 CSS 变量：

--background

、

--foreground

、

--primary

、

--secondary

、

--destructive

、

--muted-foreground

、

--border

、

--ring

。

cn() Utility

cn() 工具函数

Use

cn()

from the library (not a local

clsx

) — it includes custom Tailwind merge config for theme colors and font sizes:

tsx

import { cn } from "@lottiefiles/creator-plugins-ui";
<div className={cn("p-4 text-foreground", isActive && "bg-primary")} />

请使用库中的

cn()

（而不是本地的

clsx

）——它包含针对主题颜色和字体大小的自定义 Tailwind merge 配置：

tsx

import { cn } from "@lottiefiles/creator-plugins-ui";
<div className={cn("p-4 text-foreground", isActive && "bg-primary")} />

Common Pitfalls

常见陷阱

Missing
styles.css
import — Components render unstyled. Import
```
@lottiefiles/creator-plugins-ui/styles.css
```
once in entry file.
Using Tailwind v3 config with v4 — Do not create
```
tailwind.config.js
```
or
```
postcss.config.js
```
. Tailwind v4 uses
```
@import "tailwindcss"
```
+
```
@theme {}
```
in CSS and
```
@tailwindcss/vite
```
for Vite integration.

Using
asChild
instead of
render
— Base UI uses

render={<a href="/" />}

, not Radix's

asChild

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]
```
not
```
50
```
. Callback returns array too.
Toast requires provider —
```
useToast()
```
throws outside
```
<ToastProvider>
```
. Wrap app root.
Dark mode class placement —
```
dark
```
class goes on
```
<html>
```
or parent, not on the component.
Wrong
cn
import — Use
```
cn
```
from
```
@lottiefiles/creator-plugins-ui
```
, not a local
```
clsx
```
.

缺少
styles.css
导入 — 组件将呈现为无样式状态。在入口文件中导入一次
```
@lottiefiles/creator-plugins-ui/styles.css
```
。
在 v4 中使用 Tailwind v3 配置 — 不要创建
```
tailwind.config.js
```
或
```
postcss.config.js
```
。Tailwind v4 使用 CSS 中的
```
@import "tailwindcss"
```
+
```
@theme {}
```
，并通过
```
@tailwindcss/vite
```
与 Vite 集成。
使用
asChild
而不是
render
— Base UI 使用
```
render={<a href="/" />}
```
，而不是 Radix 的
```
asChild
```
+
```
Slot
```
。
Select 使用空字符串值 —
```
""
```
保留用于“未选择”。请改用
```
"none"
```
或类似值。
NumberInput 仅支持受控模式 — 需要
```
value
```
+
```
onChange
```
。不支持非受控模式。
Slider 的值始终为数组 — 传入
```
[50]
```
而不是
```
50
```
。回调也返回数组。
Toast 需要 Provider — 在
```
<ToastProvider>
```
外部调用
```
useToast()
```
会抛出异常。请包裹应用根节点。
暗色模式 class 的位置 —
```
dark
```
class 应放在
```
<html>
```
或父元素上，而不是组件上。
导入错误的
cn
— 请使用
```
@lottiefiles/creator-plugins-ui
```
中的
```
cn
```
，而不是本地的
```
clsx
```
。

Migration from Custom Components

从自定义组件迁移

Full before/after examples:

references/setup-guide.md

Replace
```
@stitches/react
```
styled components with library components + Tailwind classes
Replace
```
@radix-ui/*
```
imports with library components
Replace
```
asChild
```
with
```
render
```
prop

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's
```
cn()
```

完整的迁移前后示例：

references/setup-guide.md

将
```
@stitches/react
```
样式组件替换为库组件 + Tailwind 类
将
```
@radix-ui/*
```
导入替换为库组件
将
```
asChild
```
替换为
```
render
```
prop

将

data-[state=checked]

→

data-[checked]

，将

data-[state=open]

→

data-[open]

，依此类推

将内联颜色替换为 CSS 变量类（
```
text-foreground
```
、
```
bg-primary
```
）
将自定义的
```
cn()
```
/
```
clsx()
```
替换为库中的
```
cn()
```

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

参考	内容
`references/setup-guide.md`	安装、Tailwind 配置、从 Stitches/Radix 迁移、故障排除
`references/theming-guide.md`	CSS 变量、暗色模式、ThemeProvider、自定义颜色