components

Copy skill

Use the public xzero-ui MCP server at https://mcp.xzero.co.uk/mcp. The complete Free and Pro library is available through this service. No account, sign-in, token, or upstream fallback is required. If the service is unavailable, retry later; do not use upstream services.

Pick the item whose job matches, not the one that looks closest. Ids below are the install names (npx shadcn@4.23.0 add @xzero-ui/<id>). Items marked Pro need Xzero Pro (a Pro account signed in to the MCP server, or a Pro token); offer the free pick otherwise. Only ids listed here or returned by search_components exist; do not guess others.

Contents

• How to decide
• Actions and menus
• Inputs and forms
• Overlays and disclosure
• Feedback and status
• Data display and charts
• Text and motion
• App blocks
• Marketing blocks
• Wiring rules

How to decide

1. Name the job in one line ("pick one of three plans", "confirm deleting a project").
2. Find candidates in the tables below or with search_components.
3. Read each candidate's markdown (https://ui.xzero.co.uk/components/<id>/markdown or get_component). "When not to use" names the better alternative; follow it.
4. Prefer a block for a whole region, a component for a single control. Replace block sample data; do not keep placeholder names or numbers.
5. Use the same item for the same job everywhere in the app: one confirmation pattern, one menu, one table.

Actions and menus

Job	Pick	Instead of
The main action on a surface	button (its default variant is "primary"), once per surface	Several primary buttons
Other actions	button with variant="secondary" or "ghost" set explicitly	A bare <Button>, which renders primary
Dense toolbar action	action-button	Full buttons in a toolbar
Main action plus alternatives	split-button	A row of equal buttons
Navigate somewhere	A link (<a> or your router's Link), or a block action with href (hero-section, cta-section)	button with a router push
A list of actions on a trigger	dropdown-menu	Custom popovers
Actions on a right-click or long press	context-menu	Hidden gestures without a menu
Copy a value	copy-button	A button plus a toast
Label that changes with state	button (new children crossfade in place); text-morph outside a button	Swapping two buttons
Global search and commands	command-palette	A search field in every page
Account, theme, sign out	user-menu	A custom avatar menu
Hierarchy and paging	breadcrumb, pagination
Light and dark switch	theme-switch

Inputs and forms

Job	Pick	Instead of
Text	input, textarea; mention-input for @people and #channels	Unlabeled fields
Search inside a page	search-field; expanding-search in a tight header
Password	password-field, plus password-strength on sign up
Numbers, phone	number-field, phone-input	Plain input type="number"
One of 2 to 5 visible options in a form	radio-group	select
Options with a price, meta, or longer description	radio-cards	Clickable cards you build
One of many options	select; combobox to type and filter	radio-group
Several values	multi-select, tag-input, chip-group for filter facets	Checkbox lists in a popover
On or off that applies immediately	switch	checkbox
Agree, include, or a checklist inside a submitted form	checkbox	switch
View mode of the same content (2 to 5)	segmented-control	tabs
Range or level	slider	Two number fields
Date, date range, time	date-picker, date-range-picker, time-picker	calendar (inline grid only)
Color	color-picker
Files	file-dropzone (target), file-upload (full flow with progress)
Verification code	otp-input	Six inputs you wire yourself
Rich text	rich-text-editor	A textarea with markdown hints
Signature	signature-pad	A canvas you wire yourself
Keyboard shortcut	shortcut-recorder	A text field for key names
Rename in place	inline-edit	A dialog for one field
A flow in steps	stepper with your fields; Pro: multi-step-form
Billing period	billing-toggle (with BillingPrice)	A segmented control plus hand-rolled prices

Overlays and disclosure

Job	Pick	Instead of
A decision that must interrupt, or a short form	dialog	drawer
A long form, filters, or record detail beside the page	drawer	dialog
Mobile-first secondary task with snap heights	bottom-sheet	dialog on phones
Small anchored controls without dimming the page	popover	dialog
One-line hint for an unfamiliar control	tooltip	Essential information (tooltips hide it)
Preview of a person or link	hover-card (also opens on focus)
Peer panels of one object (Overview, Activity, Settings)	tabs	segmented-control
Stacked sections read in order, FAQ	accordion	tabs
A card that needs more room on request	expandable-card	Navigating away
Two panes that trade space	resizable-panels
Long content in a fixed box	scroll-area	overflow: auto with default bars

Feedback and status

Job	Pick	Instead of
Confirm a foreground action	In place: button loading, then its label	toast
Destructive action	confirm-morph; hold-to-confirm when an accidental tap must be nearly impossible; dialog when the consequence needs explaining	A modal for every delete
Result of background work	toast, toast-stack for several	Inline banners that shift layout
A message that stays until resolved	alert with tone	toast
Status label	badge with tone	Colored text alone
Known progress	progress, stepper for steps	A spinner
Loading	skeleton in the final layout	A page spinner
Nothing to show yet	empty-state with one action	"No data"
Quota or allowance	usage-meter	A bare progress bar
Site-wide notice	announcement-bar	A banner you build
People	avatar, avatar-group	Initials you draw

Data display and charts

Job	Pick	Instead of
Headline number (KPI)	metric-card (label, number, context line, change chip)	Hand-built KPI cards
Number that changes	animated-counter	Text that jumps
Records to sort and compare	sortable-data-table; Pro: data-grid for spreadsheet editing	Div grids
Filters above a collection	filter-toolbar	Loose selects
Trend over time	line-chart; sparkline beside a value
Compare one measure across categories or days	bar-chart	A line chart for categories
Share of a whole (up to about 5 parts)	donut-chart; waffle-chart for percentages; treemap for a hierarchy	A pie with many slices
Dense time series to zoom into	brush-chart	A line chart with hundreds of ticks
Before and after across items	slope-chart	Two bar charts
Distributions by group	ridgeline
Layered totals over time	streamgraph
Value against a range	gauge
A year of daily activity	activity-heatmap
Events, newest first	timeline
Nested structure	tree-view
Code or JSON	code-block, json-viewer	<pre>
Comments and chat	comment-thread, chat-thread
Feature comparison across plans or products	comparison-table (block)	A hand-built table
A row of slides	carousel
Before and after images	image-compare
Row actions on touch	swipe-actions (always with a menu path)	Swipe only

Pro charts: funnel-chart, radar-chart, sunburst, sankey-flow, race-bar-chart, realtime-stream, activity-rings.

Text and motion

Use one text effect per page, where it explains something.

Job	Pick
A title entering as it scrolls into view (once)	in-view-title
A short reveal on load	text-reveal
A label that changes to its next state	text-morph
Ongoing work ("Generating")	text-shimmer
Numbers or short text spinning to a new value	slot-text

App blocks

Free: command-palette, notification-center, file-upload, otp-input, page-header, empty-states (no results, offline, missing page), sign-in (email code card), login-centered (passkey card), signup-form.

Pro, by job:

Job	Pro blocks
App shell	sidebar-rail, workspace-sidebar, inbox-sidebar, docs-sidebar
Sign in, full screen	login-split, login-immersive
Settings and account	settings-page, security-settings, roles-permissions, api-keys, webhooks, integrations
Billing	billing-overview, usage-billing, usage-forecast, invoice-studio, cancel-flow, checkout-summary
Team	team-members, invite-people, team-directory
Analytics	metrics-dashboard, metric-explorer, revenue-explorer, cohort-retention, mrr-waterfall, journey-flow, kpi-drilldown
Boards	project-board
Setup flows	multi-step-form, release-readiness
AI	ai-chat, ai-composer, agent-run
Support and inbox	support-widget, support-conversation, inbox-triage
Commerce	product-listing, product-detail, cart-drawer
Scheduling and media	week-calendar, availability-picker, media-player

Marketing blocks

Free: site-header, hero-section, logo-marquee, stats-band, plan-comparison, comparison-table, faq-section, cta-section, newsletter-signup, contact-section, blog-grid, changelog-feed, site-footer.

Pro: hero-signup, feature-bento, scroll-story, spotlight-grid, testimonial-stage, team-showcase, pricing-calculator, usage-pricing.

Notes:

• plan-comparison is a finished two-plan demo with its own billing switch and sample data. For your own plans, compose billing-toggle, your plan cards (or radio-cards), and comparison-table (see example-pricing.md).
• Blocks with props (hero-section, cta-section, faq-section, stats-band, comparison-table, site-header) take your content directly. Blocks without props (page-header, plan-comparison) are starting points: edit their data in the installed file.

Wiring rules

• Copy the import from the usage example: import { Button } from "@/components/xzero/button/button";, import SegmentedControl from "@/components/xzero/segmented-control/segmented-control";, blocks from @/components/xzero/blocks/<id>/<id>.
• Use only documented props. Where an item accepts className or native props (check its props table), use them for layout (margin, grid placement), never to restyle internals.
• Pick controlled (value plus a change handler) or uncontrolled (defaultValue), not both.
• Async callbacks (onConfirm, onSubmit, onSave) return the promise; reject to show the item's error state. Do not add a second spinner.
• Wrap an Xzero component to add behavior; do not fork its source.