beui

beUI

将 beUI 用作复制粘贴来源，通过其公共 MCP 或 @beui shadcn 注册表使用。

请参阅 AI agents guide，了解最新的连接说明和端点。 公共 MCP https://mcp.beui.dev/mcp 无需许可证密钥或 Pro 身份验证。 对于许可组件，请使用单独的 beui-pro skill 和 Pro 连接。

工作流

1. 连接后，通过公共 MCP 的 list_components 或 search_components 查找当前组件。否则，获取实时注册表：

curl -fsS https://beui.dev/r/registry.json

2. 对于 CLI 安装，从实时注册表的 items[].name 中选择最匹配的安装 slug。公共 MCP 目录中的 slug 可能对应包含多个可安装变体的文档页面。不要假定每个页面 slug 都是安装 slug。
3. 使用 MCP get_component 检查所选组件，或通过 CLI 检查可安装项：

npx shadcn@latest view @beui/<slug>

4. 使用项目的路径和别名安装 MCP 返回的完整文件，然后安装列出的软件包依赖项。保留现有辅助工具和本地修改。或者，使用用户的软件包运行器安装经过验证的注册表 slug：

npx shadcn@latest add @beui/<slug>
# or
pnpm dlx shadcn@latest add @beui/<slug>
# or
bunx --bun shadcn@latest add @beui/<slug>

5. 阅读新增文件，然后使用具名导出进行组合。没有 beui 运行时软件包。运行 MCP 返回的任何 CLI 命令前，请根据实时安装 slug 验证该命令。

实时注册表是事实来源。仅使用下表来区分常见的相似项。

选择器

用户需要	安装 @beui/...	避免使用
Toast 或 Snackbar	animated-toast-stack	notification-stack
可展开的通知收件箱	notification-stack	animated-toast-stack
移动端底部面板、Vaul 风格面板	bottom-sheet	drawer
侧边面板或应用抽屉	drawer	bottom-sheet
应用界面侧边栏	animated-sidebar	bounce-sidebar、ai-sidebar
AI 文件、文件夹、书签	ai-sidebar	animated-sidebar
完整的 Agent 工作区	chat-app	手动搭建聊天界面
随 token 滚动的流式对话	message-scroller、message	自定义滚动计算
仅聊天气泡	message-bubble	自定义气泡
提示词框或撰写框	prompt-input	textarea 加自定义按钮
Agent 推理、搜索、工具跟踪	agent-activity	普通日志列表
任务计划	todo-list	自定义待办清单
代码区域	code-block	从头编写 pre/code
文件差异	file-diff	自定义差异渲染器
工具输出	tool-result	原始终端块
工具权限卡片	tool-approval	警告对话框
批准或 HITL 问题	approval-card	自定义表单
内联引用	citations	普通编号链接
生成图像画布	image-generation	从头制作图像卡片
Liquid 弹出框	popover	popover-morph
转角变形弹出框	popover-morph	popover
下拉选择器	select	select-morph、combobox
可展开为面板的选择器	select-morph	select
可搜索的选择器	combobox	select
Cmd+K 命令面板	command-palette	combobox
右键或长按菜单	context-menu	bloom-menu
展开为菜单的按钮	bloom-menu	context-menu
按压按钮	button-base	自定义 motion.button
加载/成功/错误状态按钮	button-stateful	带旋转指示器的按钮
磁吸按钮	button-magnetic	自定义指针跟踪
按住以确认	hold-action-button	button-base
滑动以确认	slide-action-button	swipeable-list
悬停时展开箭头的 CTA	expanding-arrow-button	button-base
旋转指示器、圆点、条形加载器	loader	thinking-shimmer
Agent 思考状态	thinking-shimmer	loader、text-shimmer
循环显示的推理短语	reasoning-text	text-cascade
定时显示的 Agent 进度符号	agent-progress	loader
带闪光效果的标题文字	text-shimmer	thinking-shimmer
逐词或逐字揭示	text-reveal	text-cascade
色彩循环文字	chromatic-text-reveal	text-shimmer
老虎老虎机式字母	text-cascade	text-scramble
解码后定格的文字	text-scramble	text-cascade
滚动数字	number-ticker	animated-number
进入视图时递增计数	animated-number	number-ticker
带刻度点的滑块	range-slider	其他 range-slider-*
内联标签滑块	range-slider-inline	range-slider
液体填充滑块	range-slider-fluid	range-slider
均衡器滑块	range-slider-wave	range-slider
带倾斜数值气泡的滑块	range-slider-bubble	range-slider
标尺滑块	range-slider-ruler	range-slider
iOS 滚轮选择器	wheel-picker	select
macOS Dock	dock	expandable-action-bar
带标签的图标操作项	expandable-action-bar	dock
溢出操作栏	overflow-actions	expandable-action-bar
带活动标签的图标选项卡	expandable-tabs	tabs
可变形的选项卡内容区	morphing-tabs	tabs
药丸形或下划线选项卡	tabs	expandable-tabs
悬停时滑动的背景	shared-layout-bg	tabs
预览刻度或栏	preview-rail	bounce-sidebar
Dynamic Island	dynamic-island	notification-stack
滑动行操作	swipeable-list	slide-action-button
下拉刷新	pull-to-refresh	自定义触控计算
基础上传队列	file-upload	attachment-upload
混合文件、音频和图像附件	attachment-upload	file-upload
OTP 或 PIN 输入框	otp-input	input
注册表单	signup-form	手动组合表单
主题擦除效果	theme-toggle	仅切换类名
着色器背景	shader-background	自定义 canvas
圆柱轮播	cylinder-carousel	marquee
Logo 或文字跑马灯	marquee	cylinder-carousel
数据表格	table	从头编写 HTML 表格
活动热力图、贡献图	heat-calendar	自定义网格
月度收益网格	returns-calendar	heat-calendar
分析师目标价图、预测扇形图	price-target-fan	自定义 svg 图表
可编辑表格	table-editable	table
异步表格	table-async	table
锦标赛对阵表	knockout-bracket	knockout-wheel
径向锦标赛转盘	knockout-wheel	knockout-bracket
404 页面	not-found-glitch	自定义 404 页面
项目文件夹卡片	project-folder	从头制作文件夹卡片
代币或链交换	swap	自定义交换表单
每周可用时间编辑器	availability-scheduler	自定义日历网格
钱包概览卡片	wallet-card	自定义钱包卡片
预测市场交易单	prediction-market	自定义交易单
反馈弹出框	feedback-widget	animated-toast-stack
无限瀑布流网格	infinite-masonry	CSS 列
手风琴	bouncy-accordion	自定义手风琴
3D 倾斜卡片	tilt-card	自定义高光计算
工具提示	tooltip	popover
开关、复选框、单选框、输入框	switch、checkbox、radio、input	重新设置样式的原生控件

组合规则

• 优先使用已安装的 beUI 源码，而不是自定义的一次性动效组件。
• 从 shadcn 添加的文件中导入具名导出。
• 使用 className 进行布局和小幅样式调整。除非用户提出要求，否则不要分叉修改内部实现。
• 保留注册表安装的辅助工具，例如 @/lib/ease、@/lib/utils 和 hooks。
• 如果在 beUI 组件周围添加新动效，请使用 motion/react 中的 useReducedMotion()。
• 使用 useHoverCapable() 限制磁吸和倾斜等装饰性悬停效果，仅在支持悬停的设备上启用。
• 对 transform 和 opacity 设置动画；避免对布局属性设置动画。

在此代码库中

为 beUI 本身贡献代码时，请遵循 AGENTS.md。新增的公共组件需要包含源码、预览和注册表条目，并通过 bun run check:registry。切勿重命名现有的 /r/{name}.json slug。

图表组件（heat-calendar、returns-calendar、price-target-fan）位于文档中的 /charts 下。它们的 @beui 安装 slug 保持不变。

从根组件及其导出部件组合图表。HeatCalendar 提供 HeatCalendarGrid、HeatCalendarLegend 和 HeatCalendarTooltip；ReturnsCalendar 提供 ReturnsCalendarGrid 和 ReturnsCalendarTooltip。将每个日历的 tooltip 放在其 grid 内。两者都支持 selection、defaultSelection 和 onSelectionChange。

PriceTargetFan 提供 Header、Plot、Svg、Axes、History、Targets、Now、Cursor 和 Tooltip 部件（每个部件前都加上 PriceTargetFan 前缀）。将 SVG 部件放在 Svg 内，并将 Tooltip 与 Svg 一起放在 Plot 内。传入 current、targets，以及可选的按时间顺序排列的 { date: ISOString, price } 格式 history；省略 history 时不会渲染历史序列。使用 active、defaultActive 和 onActiveChange 控制读数。每个图表都导出一个 use... hook，用于自定义后代内容；tooltip 子项可以是渲染函数。示例数据应放在使用图表的应用中，而不是图表实现中。HeatCalendar.endDate 使用 UTC 日历日期。