daisyui-5

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

daisyUI 5

CSS component library for Tailwind CSS 4. Provides semantic class names for common UI components.

适用于Tailwind CSS 4的CSS组件库，为常见UI组件提供语义化类名。

Install

安装

Requires Tailwind CSS 4. No
```
tailwind.config.js
```
(deprecated in v4).
Install:
```
npm i -D daisyui@latest
```
CSS file:

css

@import "tailwindcss";
@plugin "daisyui";

CDN alternative:

html

<link href="https://cdn.jsdelivr.net/npm/daisyui@5" rel="stylesheet" type="text/css" />
<script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>

依赖Tailwind CSS 4。不再需要
```
tailwind.config.js
```
（v4中已废弃）。
安装命令：
```
npm i -D daisyui@latest
```
CSS文件配置：

css

@import "tailwindcss";
@plugin "daisyui";

CDN替代方案：

html

<link href="https://cdn.jsdelivr.net/npm/daisyui@5" rel="stylesheet" type="text/css" />
<script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>

Usage Rules

使用规则

Style elements by combining: component class + part classes + modifier classes
Customize with Tailwind utility classes when daisyUI classes aren't sufficient (e.g.
```
btn px-10
```
)
Use
```
!
```
suffix on utilities as last resort for specificity (e.g.
```
btn bg-red-500!
```
)
If a component doesn't exist in daisyUI, build it with Tailwind utilities
Use Tailwind responsive prefixes for
```
flex
```
/
```
grid
```
layouts
Only use daisyUI class names or Tailwind utility classes — no custom CSS
Use
```
https://picsum.photos/{w}/{h}
```
for placeholder images
Don't add custom fonts unless necessary
Don't add
```
bg-base-100 text-base-content
```
to body unless necessary
Follow Refactoring UI best practices for design decisions

通过组合以下类来为元素设置样式：组件类 + 部件类 + 修饰符类
当daisyUI类不足以满足需求时，使用Tailwind工具类进行自定义（例如：
```
btn px-10
```
）
仅在万不得已时，使用工具类的
```
!
```
后缀来提升优先级（例如：
```
btn bg-red-500!
```
）
如果daisyUI中没有所需组件，使用Tailwind工具类构建
为
```
flex
```
/
```
grid
```
布局使用Tailwind响应式前缀
仅使用daisyUI类名或Tailwind工具类 — 不要使用自定义CSS
使用
```
https://picsum.photos/{w}/{h}
```
作为占位图片
除非必要，不要添加自定义字体
除非必要，不要为body添加
```
bg-base-100 text-base-content
```
设计决策遵循《Refactoring UI》最佳实践

Class Name Categories

类名分类

```
component
```
: Required component class
```
part
```
: Child part of a component
```
style
```
: Sets specific style
```
behavior
```
: Changes behavior
```
color
```
: Sets specific color
```
size
```
: Sets specific size
```
placement
```
/
```
direction
```
: Sets position/direction
```
modifier
```
: Modifies component
```
variant
```
: Conditional prefix (
```
variant:utility-class
```
)

```
component
```
: 必填组件类
```
part
```
: 组件的子部件类
```
style
```
: 设置特定样式
```
behavior
```
: 改变组件行为
```
color
```
: 设置特定颜色
```
size
```
: 设置特定尺寸
```
placement
```
/
```
direction
```
: 设置位置/方向
```
modifier
```
: 修饰组件
```
variant
```
: 条件前缀（
```
variant:utility-class
```
）

Colors

颜色

Semantic Color Names

语义化颜色名称

Color	Purpose
`primary` / `primary-content`	Main brand color / foreground on primary
`secondary` / `secondary-content`	Secondary brand color / foreground
`accent` / `accent-content`	Accent brand color / foreground
`neutral` / `neutral-content`	Non-saturated UI / foreground
`base-100/200/300` / `base-content`	Surface colors (light to dark) / foreground
`info` / `info-content`	Informative messages / foreground
`success` / `success-content`	Success messages / foreground
`warning` / `warning-content`	Warning messages / foreground
`error` / `error-content`	Error messages / foreground

颜色	用途
`primary` / `primary-content`	主品牌色 / 主色上的前景色
`secondary` / `secondary-content`	次要品牌色 / 次要色上的前景色
`accent` / `accent-content`	强调品牌色 / 强调色上的前景色
`neutral` / `neutral-content`	低饱和度UI色 / 中性色上的前景色
`base-100/200/300` / `base-content`	表面色（从浅到深） / 表面色上的前景色
`info` / `info-content`	提示消息色 / 提示消息上的前景色
`success` / `success-content`	成功消息色 / 成功消息上的前景色
`warning` / `warning-content`	警告消息色 / 警告消息上的前景色
`error` / `error-content`	错误消息色 / 错误消息上的前景色

Color Rules

颜色使用规则

Use daisyUI color names in Tailwind utilities:
```
bg-primary
```
,
```
text-base-content
```
Colors change automatically per theme — no
```
dark:
```
prefix needed
Avoid Tailwind color names (e.g.
```
text-gray-800
```
) — they don't adapt to themes
Use
```
base-*
```
colors for page majority,
```
primary
```
for important elements
```
*-content
```
colors must contrast well against their associated colors

在Tailwind工具类中使用daisyUI颜色名称：
```
bg-primary
```
、
```
text-base-content
```
颜色会随主题自动变化 — 无需使用
```
dark:
```
前缀
避免使用Tailwind原生颜色名称（例如：
```
text-gray-800
```
）— 它们不支持主题适配
页面主体使用
```
base-*
```
颜色，重要元素使用
```
primary
```
颜色
```
*-content
```
颜色必须与其关联颜色形成良好的对比度

Config

配置

css

@plugin "daisyui"; /* no config */

@plugin "daisyui" {
  themes: light --default, dark --prefersdark;
  root: ":root";
  include: ;
  exclude: ;
  prefix: ;
  logs: true;
}

Config options:

themes

(enable/set default),

root

include

exclude

(components),

prefix

(e.g.

daisy-

logs

css

@plugin "daisyui"; /* 无配置 */

@plugin "daisyui" {
  themes: light --default, dark --prefersdark;
  root: ":root";
  include: ;
  exclude: ;
  prefix: ;
  logs: true;
}

配置选项：

themes

（启用/设置默认主题）、

root

、

include

exclude

（组件）、

prefix

（例如：

daisy-

）、

logs

。

Custom Themes

自定义主题

css

@plugin "daisyui/theme" {
  name: "mytheme";
  default: true;
  prefersdark: false;
  color-scheme: light;
  --color-base-100: oklch(98% 0.02 240);
  --color-base-200: oklch(95% 0.03 240);
  --color-base-300: oklch(92% 0.04 240);
  --color-base-content: oklch(20% 0.05 240);
  --color-primary: oklch(55% 0.3 240);
  --color-primary-content: oklch(98% 0.01 240);
  --color-secondary: oklch(70% 0.25 200);
  --color-secondary-content: oklch(98% 0.01 200);
  --color-accent: oklch(65% 0.25 160);
  --color-accent-content: oklch(98% 0.01 160);
  --color-neutral: oklch(50% 0.05 240);
  --color-neutral-content: oklch(98% 0.01 240);
  --color-info: oklch(70% 0.2 220);
  --color-info-content: oklch(98% 0.01 220);
  --color-success: oklch(65% 0.25 140);
  --color-success-content: oklch(98% 0.01 140);
  --color-warning: oklch(80% 0.25 80);
  --color-warning-content: oklch(20% 0.05 80);
  --color-error: oklch(65% 0.3 30);
  --color-error-content: oklch(98% 0.01 30);
  --radius-selector: 1rem;
  --radius-field: 0.25rem;
  --radius-box: 0.5rem;
  --size-selector: 0.25rem;
  --size-field: 0.25rem;
  --border: 1px;
  --depth: 1;
  --noise: 0;
}

All CSS variables above are required. Colors can be OKLCH, hex, or other formats.

css

@plugin "daisyui/theme" {
  name: "mytheme";
  default: true;
  prefersdark: false;
  color-scheme: light;
  --color-base-100: oklch(98% 0.02 240);
  --color-base-200: oklch(95% 0.03 240);
  --color-base-300: oklch(92% 0.04 240);
  --color-base-content: oklch(20% 0.05 240);
  --color-primary: oklch(55% 0.3 240);
  --color-primary-content: oklch(98% 0.01 240);
  --color-secondary: oklch(70% 0.25 200);
  --color-secondary-content: oklch(98% 0.01 200);
  --color-accent: oklch(65% 0.25 160);
  --color-accent-content: oklch(98% 0.01 160);
  --color-neutral: oklch(50% 0.05 240);
  --color-neutral-content: oklch(98% 0.01 240);
  --color-info: oklch(70% 0.2 220);
  --color-info-content: oklch(98% 0.01 220);
  --color-success: oklch(65% 0.25 140);
  --color-success-content: oklch(98% 0.01 140);
  --color-warning: oklch(80% 0.25 80);
  --color-warning-content: oklch(20% 0.05 80);
  --color-error: oklch(65% 0.3 30);
  --color-error-content: oklch(98% 0.01 30);
  --radius-selector: 1rem;
  --radius-field: 0.25rem;
  --radius-box: 0.5rem;
  --size-selector: 0.25rem;
  --size-field: 0.25rem;
  --border: 1px;
  --depth: 1;
  --noise: 0;
}

上述所有CSS变量都是必填项。颜色可以使用OKLCH、十六进制或其他格式。

Creating DaisyUI Components

创建DaisyUI组件

Follow this workflow when creating or extending React components that wrap daisyUI. See references/creating-components.md for detailed patterns, compound component examples, and test templates.

创建或扩展封装daisyUI的React组件时，请遵循以下工作流程。详细模式、复合组件示例及测试模板请参考references/creating-components.md。

1. Resolve the components directory

1. 确定组件目录

Check

AGENTS.md

CLAUDE.md

for a

DAISY_COMPONENTS_DIR

variable. If not found, use

src/components/daisy

查看

AGENTS.md

或

CLAUDE.md

中的

DAISY_COMPONENTS_DIR

变量。如果未找到，使用

src/components/daisy

。

2. Ensure foundational files exist

2. 确保基础文件存在

Before creating any component, verify the project has the required infrastructure. If any are missing, create them from the bundled

scripts/

templates. See references/creating-components.md for the full bootstrapping checklist and file contents.

Required files:

<DAISY_COMPONENTS_DIR>/daisy-meta.ts

— from bundled

scripts/daisy-meta.ts

generators/daisy/generate-daisy-safelist.ts

— from bundled

scripts/generate-daisy-safelist.ts

(update the import path to point to daisy-meta.ts)

```
src/app/styles/daisy.css
```
— must import daisyUI plugin and the generated safelist
```
package.json
```
script
```
"generate:safelist"
```
— must run the generator
The
```
daisy.css
```
file must be imported in the root layout or global CSS entry point

创建任何组件之前，确认项目具备所需的基础结构。如果缺少任何文件，请从捆绑的

scripts/

模板中创建。完整的初始化检查清单和文件内容请参考references/creating-components.md。

所需文件：

<DAISY_COMPONENTS_DIR>/daisy-meta.ts

— 来自捆绑的

scripts/daisy-meta.ts

generators/daisy/generate-daisy-safelist.ts

— 来自捆绑的

scripts/generate-daisy-safelist.ts

（更新导入路径以指向daisy-meta.ts）

```
src/app/styles/daisy.css
```
— 必须导入daisyUI插件和生成的安全列表
```
package.json
```
中的脚本
```
"generate:safelist"
```
— 必须运行生成器
```
daisy.css
```
文件必须在根布局或全局CSS入口文件中导入

3. Register in daisy-meta.ts

3. 在daisy-meta.ts中注册

Add the new component's capabilities to

COMPONENT_CAPABILITIES

<DAISY_COMPONENTS_DIR>/daisy-meta.ts

. Reference the daisyUI docs (see Component Reference below) for which modifiers it supports.

在

<DAISY_COMPONENTS_DIR>/daisy-meta.ts

的

COMPONENT_CAPABILITIES

中添加新组件的功能。参考daisyUI文档（见下方组件参考）了解其支持的修饰符。

4. Create the component

4. 创建组件

Follow patterns in existing
```
<DAISY_COMPONENTS_DIR>/daisy*
```
files
Prefer compound components for multi-part daisyUI components (card, modal, dropdown, etc.)
Each sub-component in a compound component gets its own file
See references/creating-components.md for compound component structure

遵循现有
```
<DAISY_COMPONENTS_DIR>/daisy*
```
文件中的模式
对于多部分daisyUI组件（card、modal、dropdown等），优先使用复合组件模式
复合组件中的每个子组件单独创建文件
复合组件结构请参考references/creating-components.md

5. Generate safelist

5. 生成安全列表

bash

npm run generate:safelist

Generates

src/app/styles/daisy-safelist.css

bash

npm run generate:safelist

生成

src/app/styles/daisy-safelist.css

。

6. Add tests

6. 添加测试

Use the project's test framework (check

package.json

for jest/vitest). Default to Jest + React Testing Library. Test: rendering, prop variations (colors, sizes, variants), compound component composition, and accessibility.

使用项目的测试框架（查看

package.json

确认是jest还是vitest）。默认使用Jest + React Testing Library。测试内容包括：渲染、属性变体（颜色、尺寸、变体）、复合组件组合、可访问性。

7. Extend the safelist generator

7. 扩展安全列表生成器

If the new component introduces a capability modifier not yet handled in

generate-daisy-safelist.ts

, update

buildClassList()

to iterate over it.

如果新组件引入了

generate-daisy-safelist.ts

中尚未处理的功能修饰符，请更新

buildClassList()

以遍历该修饰符。

Component Reference

组件参考

Component docs are split by category. Read only the relevant file:

Layout components: See references/layout.md drawer, navbar, footer, hero, dock, divider, indicator, join, stack, fab
Data display: See references/data-display.md card, list, table, stat, badge, avatar, chat, timeline, countdown, diff, carousel, hover-3d, hover-gallery, text-rotate
Input components: See references/input.md button, input, textarea, select, checkbox, radio, toggle, range, rating, file-input, filter, fieldset, label, validator, calendar
Feedback & overlay: See references/feedback.md alert, modal, toast, loading, skeleton, progress, radial-progress, status, steps, swap, tab
Navigation & chrome: See references/navigation.md accordion, collapse, breadcrumbs, dropdown, tooltip, link, kbd, menu, mask, mockup-browser, mockup-code, mockup-phone, mockup-window, pagination, theme-controller

组件文档按类别划分，请仅阅读相关文件：

布局组件：参考references/layout.md drawer、navbar、footer、hero、dock、divider、indicator、join、stack、fab
数据展示组件：参考references/data-display.md card、list、table、stat、badge、avatar、chat、timeline、countdown、diff、carousel、hover-3d、hover-gallery、text-rotate
输入组件：参考references/input.md button、input、textarea、select、checkbox、radio、toggle、range、rating、file-input、filter、fieldset、label、validator、calendar
反馈与覆盖组件：参考references/feedback.md alert、modal、toast、loading、skeleton、progress、radial-progress、status、steps、swap、tab
导航与界面组件：参考references/navigation.md accordion、collapse、breadcrumbs、dropdown、tooltip、link、kbd、menu、mask、mockup-browser、mockup-code、mockup-phone、mockup-window、pagination、theme-controller