# March7th UI Vue

> A customizable Vue 3 component library based on shadcn-vue. Current package: `@mar7th/march7th-ui-vue@1.0.0-beta.1`.

- Official documentation and interactive demos: https://vue.march7th.online/
- npm package: https://www.npmjs.com/package/@mar7th/march7th-ui-vue
- Framework: Vue 3, TypeScript, Tailwind CSS v4, shadcn-vue and Reka UI
- Public component documentation: 66 components

## Installation

```bash
pnpm add @mar7th/march7th-ui-vue
```

Import the global styles and initialize the theme before mounting the application:

```ts
import { createApp } from "vue"
import { initializeMarch7thTheme } from "@mar7th/march7th-ui-vue/components/theme"
import "@mar7th/march7th-ui-vue/style.css"
import App from "./App.vue"

initializeMarch7thTheme()
createApp(App).mount("#app")
```

Components can be imported from the package root or a component subpath:

```ts
import { Button, Input, ToastHost } from "@mar7th/march7th-ui-vue"
import { Button } from "@mar7th/march7th-ui-vue/components/button"
import { ToastHost } from "@mar7th/march7th-ui-vue/components/toast"
```

## AI Development Rules

1. Prefer existing March7th UI components instead of recreating their markup or visual styles.
2. Read the relevant component documentation before using complex components, especially forms, overlays, navigation and composed components.
3. Import `@mar7th/march7th-ui-vue/style.css` exactly once in the application entry.
4. Call `initializeMarch7thTheme()` before mounting Vue. The default hue and hue reset target are both `215`.
5. Customize colors through `--m7-*` tokens and shadcn semantic variables instead of hard-coded component colors.
6. Use `ThemeSwitch` and `HuePicker` for theme controls.
7. Use `ToastHost` from `components/toast` with the `toast` API from `vue-sonner` for notifications.
8. The official shadcn-vue component source remains in `src/components/ui`; do not rewrite official components solely for styling changes.
9. When an API is not listed in the summary, inspect the component page or its source because many Reka UI properties and slots are forwarded.

## Documentation Guides

- [Getting Started](https://vue.march7th.online/guide/getting-started)
- [Copying Component Source](https://vue.march7th.online/guide/source-copy)
- [Theme Customization](https://vue.march7th.online/guide/theming)
- [Synchronizing Official Components](https://vue.march7th.online/guide/upstream-sync)
- [Changelog](https://vue.march7th.online/guide/changelog)

## Local Source Map

- `src/preview/catalog.ts`: component inventory, exports, common APIs and notes.
- `src/preview/examples.ts`: copyable usage examples and required component states.
- `src/components/ui/<component>`: actual component source and complete implementation behavior.
- `docs/guide/theming.md`: theme initialization, dynamic hue and semantic token documentation.

## 主题外观

- [Theme](https://vue.march7th.online/components/theme): 使用 March7th OKLCH 色相体系切换明暗模式并动态调整全局主题颜色。 Exports: `ThemeSwitch`, `HuePicker`, `useMarch7thTheme`, `initializeMarch7thTheme`, `setThemeDefaultHue`, `clampThemeHue`.

## 基础展示

- [Alert](https://vue.march7th.online/components/alert): 在页面内展示需要用户注意的状态、提示或错误信息。 Exports: `Alert`, `AlertTitle`, `AlertDescription`.
- [Aspect Ratio](https://vue.march7th.online/components/aspect-ratio): 按固定宽高比约束媒体或内容区域。 Exports: `AspectRatio`.
- [Avatar](https://vue.march7th.online/components/avatar): 显示用户头像，并在图片不可用时提供文字回退。 Exports: `Avatar`, `AvatarImage`, `AvatarFallback`.
- [Badge](https://vue.march7th.online/components/badge): 用于状态、分类、数量或短标签展示。 Exports: `Badge`, `badgeVariants`.
- [Button](https://vue.march7th.online/components/button): 触发操作的基础按钮，支持多种语义和尺寸。 Exports: `Button`, `buttonVariants`.
- [Button Group](https://vue.march7th.online/components/button-group): 将多个按钮、文本或分隔符组合成连续控件。 Exports: `ButtonGroup`, `ButtonGroupText`, `ButtonGroupSeparator`.
- [Card](https://vue.march7th.online/components/card): 承载标题、说明、内容、操作和页脚的内容容器。 Exports: `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardAction`, `CardContent`, `CardFooter`.
- [Empty](https://vue.march7th.online/components/empty): 为空状态提供图标、标题、说明和操作区域。 Exports: `Empty`, `EmptyHeader`, `EmptyMedia`, `EmptyTitle`, `EmptyDescription`, `EmptyContent`.
- [Item](https://vue.march7th.online/components/item): 统一呈现列表条目中的媒体、文本和操作。 Exports: `Item`, `ItemGroup`, `ItemHeader`, `ItemMedia`, `ItemContent`, `ItemTitle`, `ItemDescription`, `ItemActions`, `ItemFooter`, `ItemSeparator`.
- [Kbd](https://vue.march7th.online/components/kbd): 展示键盘快捷键或按键组合。 Exports: `Kbd`, `KbdGroup`.
- [Label](https://vue.march7th.online/components/label): 为表单控件提供可访问的文本标签。 Exports: `Label`.
- [Marker](https://vue.march7th.online/components/marker): 为时间线、状态列表或重点内容提供标记。 Exports: `Marker`, `MarkerIcon`, `MarkerContent`.
- [Separator](https://vue.march7th.online/components/separator): 在水平或垂直方向分隔相关内容。 Exports: `Separator`.
- [Skeleton](https://vue.march7th.online/components/skeleton): 在数据加载期间展示内容占位轮廓。 Exports: `Skeleton`.
- [Spinner](https://vue.march7th.online/components/spinner): 表示正在加载、提交或等待异步结果。 Exports: `Spinner`.
- [Table](https://vue.march7th.online/components/table): 提供结构化表格及表头、表体、页脚和空状态。 Exports: `Table`, `TableHeader`, `TableBody`, `TableFooter`, `TableHead`, `TableRow`, `TableCell`, `TableCaption`, `TableEmpty`.

## 表单输入

- [Calendar](https://vue.march7th.online/components/calendar): 用于选择单个或多个日期，并支持月份、年份切换。 Exports: `Calendar`, `CalendarHeader`, `CalendarHeading`, `CalendarGrid`, `CalendarCell`, `CalendarCellTrigger`, `CalendarPrevButton`, `CalendarNextButton`.
- [Checkbox](https://vue.march7th.online/components/checkbox): 在选中、未选中和不确定状态之间切换。 Exports: `Checkbox`.
- [Combobox](https://vue.march7th.online/components/combobox): 支持搜索、过滤和键盘选择的组合输入框。 Exports: `Combobox`, `ComboboxAnchor`, `ComboboxInput`, `ComboboxTrigger`, `ComboboxList`, `ComboboxViewport`, `ComboboxGroup`, `ComboboxItem`, `ComboboxItemIndicator`, `ComboboxEmpty`, `ComboboxSeparator`.
- [Field](https://vue.march7th.online/components/field): 组织标签、描述、输入控件、错误和字段组。 Exports: `Field`, `FieldLabel`, `FieldTitle`, `FieldDescription`, `FieldContent`, `FieldError`, `FieldGroup`, `FieldSet`, `FieldLegend`, `FieldSeparator`.
- [Form](https://vue.march7th.online/components/form): 连接 vee-validate 字段状态与标签、描述和错误信息。 Exports: `FormControl`, `FormItem`, `FormLabel`, `FormDescription`, `FormMessage`.
- [Input](https://vue.march7th.online/components/input): 统一样式的原生单行输入框。 Exports: `Input`.
- [Input Group](https://vue.march7th.online/components/input-group): 在输入框或文本域两侧组合图标、文本和按钮。 Exports: `InputGroup`, `InputGroupAddon`, `InputGroupText`, `InputGroupButton`, `InputGroupInput`, `InputGroupTextarea`.
- [Input OTP](https://vue.march7th.online/components/input-otp): 输入固定长度的一次性验证码。 Exports: `InputOTP`, `InputOTPGroup`, `InputOTPSlot`, `InputOTPSeparator`.
- [Native Select](https://vue.march7th.online/components/native-select): 保留浏览器原生选择行为的轻量下拉框。 Exports: `NativeSelect`, `NativeSelectOption`, `NativeSelectOptGroup`.
- [Number Field](https://vue.march7th.online/components/number-field): 带递增递减按钮和范围约束的数字输入。 Exports: `NumberField`, `NumberFieldContent`, `NumberFieldInput`, `NumberFieldIncrement`, `NumberFieldDecrement`.
- [Pin Input](https://vue.march7th.online/components/pin-input): 使用多个独立槽位输入 PIN、授权码或短验证码。 Exports: `PinInput`, `PinInputGroup`, `PinInputSlot`, `PinInputSeparator`.
- [Radio Group](https://vue.march7th.online/components/radio-group): 从互斥选项中选择一个值。 Exports: `RadioGroup`, `RadioGroupItem`.
- [Range Calendar](https://vue.march7th.online/components/range-calendar): 选择由开始日期和结束日期构成的日期范围。 Exports: `RangeCalendar`, `RangeCalendarHeader`, `RangeCalendarHeading`, `RangeCalendarGrid`, `RangeCalendarCell`, `RangeCalendarCellTrigger`, `RangeCalendarPrevButton`, `RangeCalendarNextButton`.
- [Select](https://vue.march7th.online/components/select): 从弹出列表中选择单个值。 Exports: `Select`, `SelectTrigger`, `SelectValue`, `SelectContent`, `SelectGroup`, `SelectLabel`, `SelectItem`, `SelectItemText`, `SelectSeparator`, `SelectScrollUpButton`, `SelectScrollDownButton`.
- [Slider](https://vue.march7th.online/components/slider): 通过拖动轨道选择单值或范围值。 Exports: `Slider`.
- [Switch](https://vue.march7th.online/components/switch): 在开启和关闭状态之间切换。 Exports: `Switch`.
- [Tags Input](https://vue.march7th.online/components/tags-input): 输入、展示和删除多个文本标签。 Exports: `TagsInput`, `TagsInputItem`, `TagsInputItemText`, `TagsInputItemDelete`, `TagsInputInput`.
- [Textarea](https://vue.march7th.online/components/textarea): 统一样式的原生多行文本输入框。 Exports: `Textarea`.
- [Toggle](https://vue.march7th.online/components/toggle): 表示可独立开启或关闭的工具按钮。 Exports: `Toggle`, `toggleVariants`.
- [Toggle Group](https://vue.march7th.online/components/toggle-group): 将多个 Toggle 组合为单选或多选工具组。 Exports: `ToggleGroup`, `ToggleGroupItem`.

## 浮层反馈

- [Accordion](https://vue.march7th.online/components/accordion): 按标题折叠和展开多个内容区域。 Exports: `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent`.
- [Alert Dialog](https://vue.march7th.online/components/alert-dialog): 要求用户明确确认或取消高风险操作。 Exports: `AlertDialog`, `AlertDialogTrigger`, `AlertDialogContent`, `AlertDialogHeader`, `AlertDialogTitle`, `AlertDialogDescription`, `AlertDialogFooter`, `AlertDialogAction`, `AlertDialogCancel`.
- [Collapsible](https://vue.march7th.online/components/collapsible): 显示或隐藏单个关联内容区域。 Exports: `Collapsible`, `CollapsibleTrigger`, `CollapsibleContent`.
- [Command](https://vue.march7th.online/components/command): 提供命令搜索、分组、快捷键提示和空状态。 Exports: `Command`, `CommandInput`, `CommandList`, `CommandEmpty`, `CommandGroup`, `CommandItem`, `CommandShortcut`, `CommandSeparator`, `CommandDialog`.
- [Context Menu](https://vue.march7th.online/components/context-menu): 在右键或长按目标区域时展示上下文操作。 Exports: `ContextMenu`, `ContextMenuTrigger`, `ContextMenuContent`, `ContextMenuItem`, `ContextMenuCheckboxItem`, `ContextMenuRadioGroup`, `ContextMenuRadioItem`, `ContextMenuLabel`, `ContextMenuSeparator`, `ContextMenuShortcut`, `ContextMenuSub`, `ContextMenuSubTrigger`, `ContextMenuSubContent`.
- [Dialog](https://vue.march7th.online/components/dialog): 在页面上方展示需要聚焦处理的内容或表单。 Exports: `Dialog`, `DialogTrigger`, `DialogContent`, `DialogScrollContent`, `DialogHeader`, `DialogTitle`, `DialogDescription`, `DialogFooter`, `DialogClose`, `DialogOverlay`.
- [Drawer](https://vue.march7th.online/components/drawer): 从屏幕边缘滑入的移动端友好操作面板。 Exports: `Drawer`, `DrawerTrigger`, `DrawerContent`, `DrawerHeader`, `DrawerTitle`, `DrawerDescription`, `DrawerFooter`, `DrawerClose`, `DrawerOverlay`.
- [Dropdown Menu](https://vue.march7th.online/components/dropdown-menu): 通过按钮触发包含普通、复选、单选和子级操作的菜单。 Exports: `DropdownMenu`, `DropdownMenuTrigger`, `DropdownMenuContent`, `DropdownMenuItem`, `DropdownMenuCheckboxItem`, `DropdownMenuRadioGroup`, `DropdownMenuRadioItem`, `DropdownMenuLabel`, `DropdownMenuSeparator`, `DropdownMenuShortcut`, `DropdownMenuSub`, `DropdownMenuSubTrigger`, `DropdownMenuSubContent`.
- [Hover Card](https://vue.march7th.online/components/hover-card): 鼠标悬停或键盘聚焦时展示补充信息。 Exports: `HoverCard`, `HoverCardTrigger`, `HoverCardContent`.
- [Menubar](https://vue.march7th.online/components/menubar): 模拟桌面应用菜单栏，支持子菜单和键盘导航。 Exports: `Menubar`, `MenubarMenu`, `MenubarTrigger`, `MenubarContent`, `MenubarItem`, `MenubarCheckboxItem`, `MenubarRadioGroup`, `MenubarRadioItem`, `MenubarLabel`, `MenubarSeparator`, `MenubarShortcut`, `MenubarSub`, `MenubarSubTrigger`, `MenubarSubContent`.
- [Popover](https://vue.march7th.online/components/popover): 围绕触发元素展示紧凑内容或轻量表单。 Exports: `Popover`, `PopoverTrigger`, `PopoverAnchor`, `PopoverContent`.
- [Sheet](https://vue.march7th.online/components/sheet): 从屏幕边缘展开的对话框式侧边面板。 Exports: `Sheet`, `SheetTrigger`, `SheetContent`, `SheetHeader`, `SheetTitle`, `SheetDescription`, `SheetFooter`, `SheetClose`, `SheetOverlay`.
- [Tooltip](https://vue.march7th.online/components/tooltip): 在悬停或聚焦时显示简短的控件说明。 Exports: `TooltipProvider`, `Tooltip`, `TooltipTrigger`, `TooltipContent`.

## 导航布局

- [Breadcrumb](https://vue.march7th.online/components/breadcrumb): 展示当前页面在信息层级中的位置。 Exports: `Breadcrumb`, `BreadcrumbList`, `BreadcrumbItem`, `BreadcrumbLink`, `BreadcrumbPage`, `BreadcrumbSeparator`, `BreadcrumbEllipsis`.
- [Carousel](https://vue.march7th.online/components/carousel): 通过拖动或按钮浏览一组连续内容。 Exports: `Carousel`, `CarouselContent`, `CarouselItem`, `CarouselPrevious`, `CarouselNext`, `useCarousel`.
- [Navigation Menu](https://vue.march7th.online/components/navigation-menu): 构建支持浮层内容和视口动画的主导航。 Exports: `NavigationMenu`, `NavigationMenuList`, `NavigationMenuItem`, `NavigationMenuTrigger`, `NavigationMenuContent`, `NavigationMenuLink`, `NavigationMenuIndicator`, `NavigationMenuViewport`, `navigationMenuTriggerStyle`.
- [Pagination](https://vue.march7th.online/components/pagination): 在多页数据之间导航并处理省略页码。 Exports: `Pagination`, `PaginationContent`, `PaginationItem`, `PaginationFirst`, `PaginationPrevious`, `PaginationNext`, `PaginationLast`, `PaginationEllipsis`.
- [Resizable](https://vue.march7th.online/components/resizable): 创建可通过拖拽分隔条调整尺寸的面板布局。 Exports: `ResizablePanelGroup`, `ResizablePanel`, `ResizableHandle`.
- [Scroll Area](https://vue.march7th.online/components/scroll-area): 提供跨浏览器一致的自定义滚动区域。 Exports: `ScrollArea`, `ScrollBar`.
- [Sidebar](https://vue.march7th.online/components/sidebar): 构建支持收起、移动端抽屉、快捷键和菜单层级的应用侧栏。 Exports: `SidebarProvider`, `Sidebar`, `SidebarHeader`, `SidebarContent`, `SidebarFooter`, `SidebarGroup`, `SidebarGroupLabel`, `SidebarGroupContent`, `SidebarMenu`, `SidebarMenuItem`, `SidebarMenuButton`, `SidebarTrigger`, `SidebarInset`.
- [Stepper](https://vue.march7th.online/components/stepper): 展示并控制多步骤流程的当前进度。 Exports: `Stepper`, `StepperItem`, `StepperTrigger`, `StepperIndicator`, `StepperTitle`, `StepperDescription`, `StepperSeparator`.
- [Tabs](https://vue.march7th.online/components/tabs): 在同一区域切换多组相关内容。 Exports: `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`.

## 数据与高级

- [Attachment](https://vue.march7th.online/components/attachment): 展示文件附件的媒体、状态、说明和操作。 Exports: `Attachment`, `AttachmentGroup`, `AttachmentMedia`, `AttachmentContent`, `AttachmentTitle`, `AttachmentDescription`, `AttachmentActions`, `AttachmentAction`, `AttachmentTrigger`.
- [Bubble](https://vue.march7th.online/components/bubble): 展示聊天气泡及其内容、分组和表情反馈。 Exports: `Bubble`, `BubbleGroup`, `BubbleContent`, `BubbleReactions`.
- [Chart](https://vue.march7th.online/components/chart): 为 Unovis 图表提供主题颜色、Tooltip 和 Legend 适配。 Exports: `ChartContainer`, `ChartStyle`, `ChartTooltipContent`, `ChartLegendContent`, `useChart`.
- [Message](https://vue.march7th.online/components/message): 组合聊天消息的头像、正文、头部和页脚信息。 Exports: `Message`, `MessageGroup`, `MessageAvatar`, `MessageHeader`, `MessageContent`, `MessageFooter`.
- [Message Scroller](https://vue.march7th.online/components/message-scroller): 为聊天消息提供锚点保持、自动滚动和回到底部能力。 Exports: `MessageScrollerProvider`, `MessageScroller`, `MessageScrollerViewport`, `MessageScrollerContent`, `MessageScrollerItem`, `MessageScrollerButton`, `useMessageScroller`.
- [Progress](https://vue.march7th.online/components/progress): 展示任务完成比例或持续处理状态。 Exports: `Progress`.
- [Toast](https://vue.march7th.online/components/toast): 基于官方 Sonner 组件提供接入 March7th 主题系统的全局通知。 Exports: `ToastHost`.