# Leaf UI

> 轻盈、自然、可定制的 React 组件库。统一的基础组件与表单，让界面自然生长。

## Guide

- [Introduction](https://ifhover.github.io/leaf-ui/en/guide/introduction.md): A UI component library for React applications. Start with a natural green theme, then make room for your own brand and ideas.
- [Installation & quick start](https://ifhover.github.io/leaf-ui/en/guide/getting-started.md): Leaf UI supports React 18 and React 19. Install the package to start using components; base and component styles load automatically.
- [Server-side rendering](https://ifhover.github.io/leaf-ui/en/guide/ssr.md): Leaf UI loads its base and component styles automatically. This page covers only framework-specific setup. See quick start for installation and component usage.
- [AI & Skills](https://ifhover.github.io/leaf-ui/en/guide/ai.md): Install the Leaf UI skill so your AI assistant can retrieve the APIs, types and examples for the version installed in your project.
- [Browser compatibility](https://ifhover.github.io/leaf-ui/en/guide/compatibility.md): Use the current or previous stable release of Chrome, Edge, Firefox or Safari.
- [Theming](https://ifhover.github.io/leaf-ui/en/guide/theming.md): Set colors, corner radii and dark mode through ConfigProvider's theme. A few settings are usually enough; related styles update automatically.
- [Tailwind CSS](https://ifhover.github.io/leaf-ui/en/guide/tailwindcss.md): Reuse Leaf UI colors, radii and spacing in Tailwind.
- [Switch languages](https://ifhover.github.io/leaf-ui/en/guide/internationalization.md): Set locale on ConfigProvider to change built-in text in date panels, empty states and clear actions.
- [Visual and interaction standard](https://ifhover.github.io/leaf-ui/en/guide/design-standards.md): Semantic colors, dimensions and spacing keep components consistent across light/dark appearance and comfortable/compact density. The full standard lives in DESIGN-STANDARDS.md in the repository. Card's small, default and large sizes adjust spacing, heading typography and heading height together, with embedded Tabs following the card size by default. Tabs share the heading area: they sit beneath a title or fill the entire heading height with vertically centered labels when no title is provided. The divider runs only below the entire tab bar. Labels and content share the Card content edge and insets, while divided continues to control the footer treatment. Warnings use a bright amber consistently for icons, field borders and status fills, with independently derived readable text colors. Customize the warning color through ConfigProvider's theme.tokens.warningColor. Options share a neutral gray background for hover and keyboard candidates; selected values retain a primary tint, semantic text and checkmarks. Select, AutoComplete, Cascader, TreeSelect, time lists and menus follow this palette; AutoComplete, Mentions and CommandPalette candidates stay neutral. Moving backgrounds smoothly change position and color without stacking fills over selected rows. Disabled options receive no interaction feedback, and danger actions retain red accents. Colors follow the regional ConfigProvider theme and light or dark appearance. Select, TreeSelect and Cascader share selected-tag sizes and spacing. Tags wrap by default; tagWrap={false} keeps one line and collapses overflow into +N. Long labels truncate while preserving room for search and actions. Folding affects presentation only, never selected values. Solid and outlined buttons emit a wave that quickly expands outside their contour, then slowly fades, while the button and label remain stable; soft and link buttons do not emit a wave. Solid buttons brighten on hover and deepen on press; outlined buttons change text and border colors. Soft buttons use a subtle neutral surface, with a pale red surface and red text for danger actions; the background deepens on hover and press. Menus and tabs use color, opacity, borders and shadows for feedback; selected indicators may move to the selected item. Drawers slide smoothly; feedback enters as a unit without separate icon/text springs. Buttons omit the wave when regional motion is disabled or system reduced motion is enabled; the system preference takes precedence. Radius, borders and type build the hierarchy together. Radii step down from the outside in: dialogs, drawers and popups use the large radius; content surfaces such as cards, alerts and choice cards use the medium radius; buttons, fields and table frames use the base radius; checkboxes and other small elements use the small radius; status tags use borderless fills and the base radius. Content surfaces are separated by hairline borders and muted fills, not shadows; shadows are reserved for layers that actually float, such as popups, dialogs, dragged items and slider handles. Type hierarchy comes from size and color: 14px body, 13px secondary text, weight 600 for Card titles and document headings, and 500 for other component titles, labels and buttons. Option group headings use a 12px tracked muted style. Inset backgrounds use nested curves: inner radius = max(0px, outer radius - padding - border width). The default popup has a 16px outer radius, 6px padding and a 1px border, so options use 9px. Hover, selected and moving highlights share the same curve and follow theme changes. Unequal padding is calculated per direction; additional insets in nested structures are included. Small and square themes clamp to zero. Independent controls, calendar cells, tags and icons keep their semantic radii. Menu navigation items, hover backgrounds and moving selection highlights use the same base radius as buttons, independent of menu padding. A Menu radius override updates these curves together. Selectable items change only text and icon colors on hover, keyboard focus and press, preserving their backgrounds. Submenu triggers use a subtle hover background that deepens on press. Ancestors retain their normal appearance when a descendant is selected. Submenus use muted text and 32px rows (26px in compact density); navigation popups share the same feedback. Pagination defaults to outlined buttons, with a borderless alternative. Both follow control-height tokens and retain their geometry on press, with a moving selection background. Outlined controls change text and border color; ghost controls use neutral fills. Card-style Tabs use matching inner radii for tabs and the moving selection background, derived from the bar radius minus its actual padding and border and clamped at zero. Regional themes and component radius overrides feed the same calculation. The bar fits its labels and its size includes borders and padding; content panels retain the available width. Card tabs use 3 px padding and gaps, neutral text and a raised selected surface; pressing never scales a tab. Set block for equal widths and omit item content for a header-only view switcher. Tag provides borderless tinted and solid fills with the theme's base radius (10px by default). A component radius override takes precedence. Tag, CheckableTag and TagGroup use bold labels following the theme's headingWeight (600 by default). Set bold={false} for regular weight, or configure bold through regional component defaults. Acceptance covers default, hover, pressed, focus-visible, selected, disabled, loading, error and empty states. Text or ARIA must also express state. Icon-only actions need accessible names. Align icons with labels and dialog form edges with footer actions. Compact density suits pointer/keyboard interfaces and keeps body text readable. Prefer comfortable or larger explicit controls on touch; essential targets should be at least 24px, preferably 44px. Local component settings and explicit theme dimensions override density and defaults. Button inline padding follows its actual height, and component-level padding applies to every size. Small Steps keep body-size labels; card and list choice groups share a quiet section heading. Card headings have equal top and bottom insets, without duplicate spacing where they meet the body. Modal keeps a heading icon and subtle section dividers. Confirm is a compact API prompt with a bare icon beside its explanation and spacing-based sections. Headers without a description have less vertical space; divided Card, Modal and Drawer actions share compact footer spacing; Confirm uses the same bottom inset. Steps labels have transparent backgrounds, with horizontal connectors placed after the text. Avatars use a single 2px white border, including overlapping groups, without an extra outline shadow. DataTable defaults to borderless striped rows. Borderless tables have square corners and untinted headers. Bordered tables use the base radius and muted headers; both modes use body text color for headings. Borderless headers keep a 2px bottom divider; stripes hide row dividers, while striped={false} restores fine row dividers. Enable bordered for the outer frame and column dividers; stripes blend the muted and table surfaces equally, and hover adds a subtle 3% primary tint to each row's base background, including striped rows. Link buttons have no background, border, padding or fixed control height. Hover and press change text color without a wave. Use Link for navigation and the Button link variant for text actions.
- [Installation & quick start](https://ifhover.github.io/leaf-ui/en/guide/installation.md)
- [Workspace composition](https://ifhover.github.io/leaf-ui/en/guide/workspace.md): Use Layout for the page shell, Flex and Grid for layout, Form for editing, and DataTable for structured data. Keep authentication, persistence and request cancellation in application code. Component pages show focused API examples.

## Components

- [Components](https://ifhover.github.io/leaf-ui/en/components/index.md): Browse components, examples and API references.
- [Icons](https://ifhover.github.io/leaf-ui/en/components/icons.md): Leaf UI's internal icons and the examples on this page use Lucide, but lucide-react is one of many options. Button's startIcon / endIcon and Input's prefix / suffix accept ReactNode, so you can use React components from other icon libraries.
- [ConfigProvider](https://ifhover.github.io/leaf-ui/en/components/config-provider.md): Set a shared theme, language and component defaults for an application or a local region. Wrap the application to configure it globally, or nest providers to customize one region.
- [Typography](https://ifhover.github.io/leaf-ui/en/components/typography.md): Organize headings, body text and links.
- [Button](https://ifhover.github.io/leaf-ui/en/components/button.md): Trigger an action, such as saving, submitting or deleting.
- [Divider](https://ifhover.github.io/leaf-ui/en/components/divider.md): Separate content, paragraphs or actions.
- [Splitter](https://ifhover.github.io/leaf-ui/en/components/splitter.md): Resize panels in a workspace.
- [Layout](https://ifhover.github.io/leaf-ui/en/components/layout.md): Organize headers, sidebars, content and footers.
- [Grid](https://ifhover.github.io/leaf-ui/en/components/grid.md): Arrange content for different screen widths.
- [Flex](https://ifhover.github.io/leaf-ui/en/components/flex.md): Control direction, alignment, spacing and wrapping without adding wrappers around children.
- [Space](https://ifhover.github.io/leaf-ui/en/components/space.md): Keep consistent spacing between elements.
- [ScrollArea](https://ifhover.github.io/leaf-ui/en/components/scroll-area.md): Browse content inside a bounded scroll area.
- [Scrollbar](https://ifhover.github.io/leaf-ui/en/components/scrollbar.md): Browse long or wide content inside a region.
- [Masonry](https://ifhover.github.io/leaf-ui/en/components/masonry.md): Arrange cards and images of varying heights.
- [AppBar](https://ifhover.github.io/leaf-ui/en/components/app-bar.md): Organize navigation at the top and bottom of an application.
- [CommandPalette](https://ifhover.github.io/leaf-ui/en/components/command-palette.md): Search and run actions quickly.
- [FloatButton](https://ifhover.github.io/leaf-ui/en/components/float-button.md): Keep quick actions within reach.
- [Anchor](https://ifhover.github.io/leaf-ui/en/components/anchor.md): Navigate long pages and keep important actions visible.
- [Menu](https://ifhover.github.io/leaf-ui/en/components/menu.md): Organize hierarchical navigation.
- [BackTop](https://ifhover.github.io/leaf-ui/en/components/back-top.md): Return to the top of a page or scroll container.
- [Steps](https://ifhover.github.io/leaf-ui/en/components/steps.md): Show the progress and current step of a task.
- [Breadcrumb](https://ifhover.github.io/leaf-ui/en/components/breadcrumb.md): Show the current page within a navigation hierarchy.
- [Pagination](https://ifhover.github.io/leaf-ui/en/components/pagination.md): Browse large datasets one page at a time.
- [Tabs](https://ifhover.github.io/leaf-ui/en/components/tabs.md): Switch between content views within the same region. Content and panel height update immediately without transition animations. The tab bar's selection indicator keeps its movement animation. The card-style tab bar fits its labels by default and scrolls within the bar when space is limited. size controls the entire 30 / 36 / 42 px bar, including its 3 px padding and border. Tabs use a 3 px gap, a muted background and a raised selected surface that is pure white in light mode and follows the theme's raised surface color in dark mode. Pressing a tab keeps its size. Set block for equal-width tabs; content panels use the available width.
- [Statistic](https://ifhover.github.io/leaf-ui/en/components/statistic.md): Display metrics and countdowns. Numbers initially count up or down from 0 to the target. Later changes animate from the currently displayed value to the new target.
- [DataTable](https://ifhover.github.io/leaf-ui/en/components/table.md): Browse, filter and manage structured data.
- [Descriptions](https://ifhover.github.io/leaf-ui/en/components/descriptions.md): Present object details as labels and values.
- [QRCode](https://ifhover.github.io/leaf-ui/en/components/qr-code.md): Present text and links as QR codes.
- [Timeline](https://ifhover.github.io/leaf-ui/en/components/timeline.md): Present events and progress in sequence.
- [VirtualList](https://ifhover.github.io/leaf-ui/en/components/virtual-list.md): Browse large lists smoothly.
- [InfiniteScroll](https://ifhover.github.io/leaf-ui/en/components/infinite-scroll.md): Load more content when reaching the end of a list.
- [Tag](https://ifhover.github.io/leaf-ui/en/components/tag.md): Label content categories or statuses.
- [Badge](https://ifhover.github.io/leaf-ui/en/components/badge.md): Show counts, unread notifications or brief statuses.
- [Avatar](https://ifhover.github.io/leaf-ui/en/components/avatar.md): Display an avatar for a user, team or object.
- [Card](https://ifhover.github.io/leaf-ui/en/components/card.md): Group related content and actions in a container. Titles use a semibold weight of 600 by default. Customize it through ConfigProvider's theme.headingWeight.
- [Collapse](https://ifhover.github.io/leaf-ui/en/components/collapse.md): Expand or collapse a group of sections.
- [Tree](https://ifhover.github.io/leaf-ui/en/components/tree.md): Browse, select and check hierarchical content.
- [Carousel](https://ifhover.github.io/leaf-ui/en/components/carousel.md): Browse images or content one slide at a time.
- [Image](https://ifhover.github.io/leaf-ui/en/components/image.md): Display images and explore galleries.
- [FileList](https://ifhover.github.io/leaf-ui/en/components/file-list.md): Display file information and upload status, with preview, download and removal actions.
- [Mentions](https://ifhover.github.io/leaf-ui/en/components/mentions.md): Insert people or references into text.
- [Upload](https://ifhover.github.io/leaf-ui/en/components/upload.md): Choose or drop files and follow upload progress.
- [Transfer](https://ifhover.github.io/leaf-ui/en/components/transfer.md): Select and move items between two lists.
- [InputOTP](https://ifhover.github.io/leaf-ui/en/components/input-otp.md): Enter and paste verification codes.
- [InputMask](https://ifhover.github.io/leaf-ui/en/components/input-mask.md): Enter information in a specified format.
- [Input](https://ifhover.github.io/leaf-ui/en/components/input.md): Enter a single line of text.
- [InputNumber](https://ifhover.github.io/leaf-ui/en/components/input-number.md): Enter numeric values such as quantities or prices.
- [Textarea](https://ifhover.github.io/leaf-ui/en/components/textarea.md): Enter multiple lines of text.
- [Checkbox](https://ifhover.github.io/leaf-ui/en/components/checkbox.md): Select one or more options.
- [Radio](https://ifhover.github.io/leaf-ui/en/components/radio.md): Choose one option from a group.
- [Switch](https://ifhover.github.io/leaf-ui/en/components/switch.md): Turn a setting on or off.
- [Slider](https://ifhover.github.io/leaf-ui/en/components/slider.md): Choose a number or range by sliding.
- [Rate](https://ifhover.github.io/leaf-ui/en/components/rate.md): Select or display a rating.
- [Select](https://ifhover.github.io/leaf-ui/en/components/select.md): Choose one or several options from a dropdown list.
- [AutoComplete](https://ifhover.github.io/leaf-ui/en/components/auto-complete.md): Suggest values while allowing free-text input.
- [Cascader](https://ifhover.github.io/leaf-ui/en/components/cascader.md): Choose a value through a hierarchy of options.
- [TreeSelect](https://ifhover.github.io/leaf-ui/en/components/tree-select.md): Choose one or more values from hierarchical data.
- [ColorPicker](https://ifhover.github.io/leaf-ui/en/components/color-picker.md): Choose colors for content and branding.
- [Form](https://ifhover.github.io/leaf-ui/en/components/form.md): Organize fields, labels and validation feedback, and collect form data.
- [TimeRangePicker](https://ifhover.github.io/leaf-ui/en/components/time-range-picker.md): Choose a start and end time.
- [DatePicker](https://ifhover.github.io/leaf-ui/en/components/date-picker.md): Choose a date from a calendar.
- [TimePicker](https://ifhover.github.io/leaf-ui/en/components/time-picker.md): Choose a time.
- [DateTimePicker](https://ifhover.github.io/leaf-ui/en/components/date-time-picker.md): Select a specific date and time.
- [DateRangePicker](https://ifhover.github.io/leaf-ui/en/components/date-range-picker.md): Select start and end dates or times to define a range.
- [Calendar](https://ifhover.github.io/leaf-ui/en/components/calendar.md): Browse and select dates, and display schedules.
- [Tour](https://ifhover.github.io/leaf-ui/en/components/tour.md): Introduce features in a sequence of steps.
- [Notification](https://ifhover.github.io/leaf-ui/en/components/notification.md): Present notifications and actions in a page corner.
- [Popconfirm](https://ifhover.github.io/leaf-ui/en/components/popconfirm.md): Confirm important actions near their triggers.
- [ErrorBoundary](https://ifhover.github.io/leaf-ui/en/components/error-boundary.md): Provide a fallback when content fails to render.
- [LoadingBar](https://ifhover.github.io/leaf-ui/en/components/loading-bar.md): Show page or task loading progress.
- [Dropdown](https://ifhover.github.io/leaf-ui/en/components/dropdown.md): Group additional actions in a menu.
- [Modal](https://ifhover.github.io/leaf-ui/en/components/modal.md): Display content or complete an action in a dialog.
- [Drawer](https://ifhover.github.io/leaf-ui/en/components/drawer.md): Open content from a page edge to view details or complete actions.
- [Confirm](https://ifhover.github.io/leaf-ui/en/components/confirm.md): Ask for confirmation before an important action. Call the API and await the user's choice.
- [Alert](https://ifhover.github.io/leaf-ui/en/components/alert.md): Show a result or information that needs attention within a page.
- [Result](https://ifhover.github.io/leaf-ui/en/components/result.md): Present operation results, empty content and other states.
- [Message](https://ifhover.github.io/leaf-ui/en/components/message.md): Provide brief feedback about an operation.
- [Loading](https://ifhover.github.io/leaf-ui/en/components/loading.md): Indicate that content is loading or an operation is in progress.
- [Skeleton](https://ifhover.github.io/leaf-ui/en/components/skeleton.md): Show a content placeholder while loading.
- [Progress](https://ifhover.github.io/leaf-ui/en/components/progress.md): Display task completion.
- [Tooltip](https://ifhover.github.io/leaf-ui/en/components/tooltip.md): Add a brief explanation to a page element.
- [Popover](https://ifhover.github.io/leaf-ui/en/components/popover.md): Show details or actions next to an element.
- [Empty](https://ifhover.github.io/leaf-ui/en/components/empty.md): Empty states are now part of Result. Use Result with status="empty". The Empty export remains as a compatibility entry.

## API

- [API reference](https://ifhover.github.io/leaf-ui/en/api/index.md): Complete configuration fields for applications that need more control. For everyday setup and runnable examples, start with ConfigProvider.
- [Component defaults](https://ifhover.github.io/leaf-ui/en/api/component-defaults.md): Use components on ConfigProvider to set shared default props. See component defaults for examples, naming rules and inheritance.
- [Theme tokens](https://ifhover.github.io/leaf-ui/en/api/theme-tokens.md): Prefer ConfigProvider's theme.primaryColor, theme.borderRadius and theme.controlHeight for everyday customization. Related styles derive automatically; see theming.
- [PopupOptions](https://ifhover.github.io/leaf-ui/en/api/popup-options.md): Shared popup settings for Select, date and time pickers, and related components. Component settings override ConfigProvider's getPopupContainer. Modal and Drawer call their mounting-container prop container.
- [Translation resources](https://ifhover.github.io/leaf-ui/en/api/translations.md): Add languages with ConfigProvider translations. Use locale to choose the active language and fallback order. Runnable example.

## Changelog

- [Changelog](https://ifhover.github.io/leaf-ui/en/changelog.md): Features, improvements and fixes included in each npm release.