{ onKeyDown?.(event); if (event.defaultPrevented) return; if (event.key === "Enter" || event.key === " ") { event.preventDefault(); event.currentTarget.click(); } } : onKeyDown } className={cn( "overflow-hidden border border-gray-6 bg-gray-2 rounded-(--radius-md)", clickable && "cursor-pointer transition-colors motion-reduce:transition-none hover:border-gray-8 hover:shadow-[0_2px_8px_var(--gray-a3)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-gray-8", className )} {...props} /> ); } function CardHeader({ className, ...props }: React.ComponentProps<"div">) { return (

); } function CardTitle({ className, ...props }: React.ComponentProps<"h3">) { return (

); } function CardDescription({ className, ...props }: React.ComponentProps<"p">) { return (
); } /** * Right-hand slot of CardHeader. Place it as a direct child so it sits at the top right, beside the title and description. */ function CardAction({ className, ...props }: React.ComponentProps<"div">) { return (
); } function CardContent({ className, ...props }: React.ComponentProps<"div">) { return (
); } function CardFooter({ className, ...props }: React.ComponentProps<"div">) { return (
); } export { Card, CardHeader, CardFooter, CardTitle, CardAction, CardDescription, CardContent, }; ``` Copy and paste the chart component into your `components/ui/Chart.tsx` file. ```tsx "use client"; /** * @description Chart container, tooltip, legend, and series wrappers for Recharts, colored with Aura series tokens. / import as React from "react"; import { Area, Bar, Legend, Line, Pie, Radar, RadialBar, ResponsiveContainer, Tooltip, } from "recharts"; import { cn } from "@/utils/class-names"; const THEMES = { light: "", dark: ".dark" } as const; type SeriesColor = { color?: string; theme?: never; } | { color?: never; theme: Partial>; }; export type ChartConfig = { [key: string]: { label?: React.ReactNode; icon?: React.ComponentType<{ className?: string }>; } & SeriesColor; }; type ChartTooltipItem = { type?: string; dataKey?: string | number; name?: string; value?: number | string; color?: string; payload?: Record & { fill?: string }; fill?: string; }; type ChartContextValue = { config: ChartConfig; reducedMotion: boolean; }; const ChartContext = React.createContext(null); function usePrefersReducedMotion() { return React.useSyncExternalStore( (onStoreChange) => { const media = window.matchMedia("(prefers-reduced-motion: reduce)"); media.addEventListener("change", onStoreChange); return () => media.removeEventListener("change", onStoreChange); }, () => window.matchMedia("(prefers-reduced-motion: reduce)").matches, () => false ); } function useChart() { const context = React.useContext(ChartContext); if (!context) { throw new Error("useChart must be used within a "); } return context; } const VAR_COLOR = /^var$--[a-zA-Z0-9_-]+(?:\s,\s(?:#[0-9a-fA-F]{3,8}|[a-zA-Z]+))?$$/; const HEX_COLOR = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/; const NAMED_COLOR = /^[a-zA-Z]+$/; const FUNC_COLOR = /^(?:rgb|rgba|hsl|hsla|hwb|lab|lch|oklab|oklch|color|color-mix)$(?:[^()]|\([^()]$)+\)$/; function isSafeChartColor(value: string) { if (/[;{}\\]|url\s\(|\/\|\\//i.test(value)) return false; return ( VAR_COLOR.test(value) || HEX_COLOR.test(value) || NAMED_COLOR.test(value) || FUNC_COLOR.test(value) ); } function tokenColor(color: string | undefined) { if (!color) return undefined; const value = color.trim(); if (!value) return undefined; if (isSafeChartColor(value)) return value; if (process.env.NODE_ENV !== "production") { console.warn( `[chart] Ignored color "${value}". Use a var(--token), hex, rgb(), hsl(), or a CSS named color.` ); } return undefined; } const CHART_INSET_FALLBACK = 13; let chartInsetCache: number | undefined; function measureCssPx(expression: string, fallback: number) { if (typeof document === "undefined") return fallback; const probe = document.createElement("div"); probe.style.position = "absolute"; probe.style.visibility = "hidden"; probe.style.pointerEvents = "none"; probe.style.inlineSize = expression; document.documentElement.appendChild(probe); const width = probe.getBoundingClientRect().width; probe.remove(); return Number.isFinite(width) && width > 0 ? width : fallback; } /** Pixel size of `--chart-inset`, which follows `--spacing`. / function chartInsetPx() { if (chartInsetCache != null) return chartInsetCache; const value = measureCssPx( "var(--chart-inset, var(--spacing, 13px))", CHART_INSET_FALLBACK ); if (typeof document !== "undefined") chartInsetCache = value; return value; } function chartTickMargin() { return chartInsetPx(); } function chartPlotMargin(overrides?: { top?: number; right?: number; left?: number; bottom?: number; }) { const inset = chartInsetPx(); return { top: inset, right: inset, left: inset, bottom: 0, ...overrides, }; } const chartAxisTick = { fill: "var(--chart-tick, var(--gray-11))", fontSize: "var(--chart-tick-size, var(--spacing))", }; function ChartContainer({ id, className, children, config, label, ...props }: React.ComponentProps<"div"> & { config: ChartConfig; children: React.ComponentProps["children"]; label?: string; }) { const uniqueId = React.useId(); const chartId = `chart-${id || uniqueId.replace(/:/g, "")}`; const reducedMotion = usePrefersReducedMotion(); return (
{children}
); } function ChartStyle({ id, config }: { id: string; config: ChartConfig }) { const colorConfig = Object.entries(config).filter( ([, item]) => item.theme || item.color ); if (!colorConfig.length) return null; const css = Object.entries(THEMES) .map(([theme, prefix]) => { const lines = colorConfig .map(([key, item]) => { const color = tokenColor( item.theme?.[theme as keyof typeof item.theme] || item.color ) ?? undefined; return color ? ` --color-${key}: ${color};` : null; }) .filter(Boolean) .join("\n"); if (!lines) return ""; return `${prefix} [data-chart=${id}] {\n${lines}\n}`; }) .filter(Boolean) .join("\n"); if (!css) return null; return
); } function useReduced() { const [reduced, setReduced] = React.useState(false); React.useEffect(() => { const query = window.matchMedia("(prefers-reduced-motion: reduce)"); const update = () => setReduced(query.matches); update(); query.addEventListener("change", update); return () => query.removeEventListener("change", update); }, []); return reduced; } export { Marquee }; ``` # Mask Input (/docs/components/mask-input) ## Preview [#preview] ```tsx import as React from "react"; import { MaskInput, type MaskPattern } from "@/components/ui/MaskInput"; export function MaskInputDemo() { const [phone, setPhone] = React.useState(""); return (
Phone number setPhone(masked)} />
Masked value: {phone || "—"}

); } ``` ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/mask-input ``` ### Manual [#manual] Install the following dependencies: ```bash pnpm install radix-ui ``` Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` Copy and paste the compose refs utility into your `utils/compose-refs.tsx` file. ```tsx /** * @see https://github.com/radix-ui/primitives/blob/main/packages/react/compose-refs/src/compose-refs.tsx / import as React from "react"; type PossibleRef = React.Ref | undefined; /** * Set a given ref to a given value * This utility takes care of different types of refs: callback refs and RefObject(s) */ function setRef(ref: PossibleRef, value: T) { if (typeof ref === "function") { return ref(value); } if (ref !== null && ref !== undefined) { ref.current = value; } } /** * A utility to compose multiple refs together * Accepts callback refs and RefObject(s) */ function composeRefs(...refs: PossibleRef[]): React.RefCallback { return (node) => { let hasCleanup = false; const cleanups = refs.map((ref) => { const cleanup = setRef(ref, node); if (!hasCleanup && typeof cleanup === "function") { hasCleanup = true; } return cleanup; }); // React <19 will log an error to the console if a callback ref returns a // value. We don't use ref cleanups internally so this will only happen if a // user's ref callback returns a value, which we only expect if they are // using the cleanup functionality added in React 19. if (hasCleanup) { return () => { for (let i = 0; i < cleanups.length; i++) { const cleanup = cleanups[i]; if (typeof cleanup === "function") { cleanup(); } else { setRef(refs[i], null); } } }; } }; } /** * A custom hook that composes multiple refs * Accepts callback refs and RefObject(s) */ function useComposedRefs(...refs: PossibleRef[]): React.RefCallback { // biome-ignore lint/correctness/useExhaustiveDependencies: we want to memoize by all values return React.useCallback(composeRefs(...refs), refs); } export { composeRefs, useComposedRefs }; ``` Copy and paste the MaskInput component into your `components/ui/MaskInput.tsx` file. ```tsx "use client"; /** * @description Input that formats values with built-in or custom mask patterns. / import as React from "react"; import { Slot as SlotPrimitive } from "radix-ui"; import { useComposedRefs } from "@/utils/compose-refs"; import { cn } from "@/utils/class-names"; const PAST_YEARS_LIMIT = 120; const FUTURE_YEARS_LIMIT = 10; const DEFAULT_CURRENCY = "USD"; const DEFAULT_LOCALE = "en-US"; const NUMERIC_MASK_PATTERNS = /^(phone|zipCode|zipCodeExtended|ssn|ein|time|date|creditCard|creditCardExpiry)$/; const CURRENCY_PERCENTAGE_SYMBOLS = /[€$%]/; interface CurrencySymbols { currency: string; decimal: string; group: string; } const formattersCache = new Map(); const currencyAtEndCache = new Map(); const currencySymbolsCache = new Map(); const daysInMonthCache = [ 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31, ] as const; const REGEX_CACHE = { digitsOnly: /^\d+$/, nonDigits: /\D/g, nonAlphaNumeric: /[^A-Z0-9]/gi, nonNumericDot: /[^0-9.]/g, nonCurrencyChars: /[^\d.,]/g, hashPattern: /#/g, currencyAtEnd: /\d\s[^\d\s]+$/, percentageChars: /[^\d.]/g, phone: /^\d{10}$/, ssn: /^\d{9}$/, zipCode: /^\d{5}$/, zipCodeExtended: /^\d{9}$/, isbn: /^\d{13}$/, ein: /^\d{9}$/, time: /^\d{4}$/, creditCard: /^\d{13,19}$/, creditCardExpiry: /^\d{4}$/, licensePlate: /^[A-Z0-9]{6}$/, macAddress: /^[A-F0-9]{12}$/, currencyValidation: /^\d+(\.\d{1,2})?$/, ipv4Segment: /^\d{1,3}$/, } as const; function getCachedFormatter( locale: string | undefined, opts: Intl.NumberFormatOptions, ): Intl.NumberFormat { const { currency, minimumFractionDigits = 0, maximumFractionDigits = 2, } = opts; const key = `${locale}|${currency}|${minimumFractionDigits}|${maximumFractionDigits}`; if (!formattersCache.has(key)) { try { formattersCache.set( key, new Intl.NumberFormat(locale, { style: "currency", currency, ...opts, }), ); } catch { formattersCache.set( key, new Intl.NumberFormat(DEFAULT_LOCALE, { style: "currency", currency: DEFAULT_CURRENCY, ...opts, }), ); } } const formatter = formattersCache.get(key); if (!formatter) { throw new Error(`Failed to create formatter for ${key}`); } return formatter; } function getCachedCurrencySymbols(opts: TransformOptions): CurrencySymbols { const { locale, currency } = opts; const key = `${locale}|${currency}`; const cached = currencySymbolsCache.get(key); if (cached) { return cached; } let currencySymbol = "$"; let decimalSeparator = "."; let groupSeparator = ","; try { const formatter = getCachedFormatter(locale, { currency, minimumFractionDigits: 0, maximumFractionDigits: 2, }); const parts = formatter.formatToParts(1234.5); const currencyPart = parts.find((part) => part.type === "currency"); const decimalPart = parts.find((part) => part.type === "decimal"); const groupPart = parts.find((part) => part.type === "group"); if (currencyPart) currencySymbol = currencyPart.value; if (decimalPart) decimalSeparator = decimalPart.value; if (groupPart) groupSeparator = groupPart.value; } catch { // Keep defaults } const symbols: CurrencySymbols = { currency: currencySymbol, decimal: decimalSeparator, group: groupSeparator, }; currencySymbolsCache.set(key, symbols); return symbols; } function isCurrencyAtEnd(opts: TransformOptions): boolean { const { locale, currency } = opts; const key = `${locale}|${currency}`; const cached = currencyAtEndCache.get(key); if (cached !== undefined) { return cached; } try { const formatter = getCachedFormatter(locale, { currency, minimumFractionDigits: 0, maximumFractionDigits: 0, }); const sample = formatter.format(123); const result = REGEX_CACHE.currencyAtEnd.test(sample); currencyAtEndCache.set(key, result); return result; } catch { currencyAtEndCache.set(key, false); return false; } } function isCurrencyMask(opts: { mask: MaskPatternKey | MaskPattern | undefined; pattern?: string; }): boolean { const { mask, pattern } = opts; return ( mask === "currency" || Boolean(pattern && (pattern.includes("$") || pattern.includes("€"))) ); } interface TransformOptions { currency?: string; locale?: string; } interface ValidateOptions { min?: number; max?: number; } interface MaskPattern { pattern: string; transform?: (value: string, opts?: TransformOptions) => string; validate?: (value: string, opts?: ValidateOptions) => boolean; } type MaskPatternKey = | "phone" | "ssn" | "date" | "time" | "creditCard" | "creditCardExpiry" | "zipCode" | "zipCodeExtended" | "currency" | "percentage" | "licensePlate" | "ipv4" | "macAddress" | "isbn" | "ein"; const MASK_PATTERNS: Record = { phone: { pattern: "(###) ###-####", transform: (value) => value.replace(REGEX_CACHE.nonDigits, ""), validate: (value) => REGEX_CACHE.phone.test(value.replace(REGEX_CACHE.nonDigits, "")), }, ssn: { pattern: "###-##-####", transform: (value) => value.replace(REGEX_CACHE.nonDigits, ""), validate: (value) => REGEX_CACHE.ssn.test(value.replace(REGEX_CACHE.nonDigits, "")), }, date: { pattern: "##/##/####", transform: (value) => value.replace(REGEX_CACHE.nonDigits, ""), validate: (value) => { const cleaned = value.replace(REGEX_CACHE.nonDigits, ""); if (cleaned.length !== 8) return false; const month = parseInt(cleaned.substring(0, 2), 10); const day = parseInt(cleaned.substring(2, 4), 10); const year = parseInt(cleaned.substring(4, 8), 10); const currentYear = new Date().getFullYear(); const minYear = currentYear - PAST_YEARS_LIMIT; const maxYear = currentYear + FUTURE_YEARS_LIMIT; if ( month < 1 || month > 12 || day < 1 || year < minYear || year > maxYear ) return false; const maxDays = month === 2 && ((year % 4 === 0 && year % 100 !== 0) || year % 400 === 0) ? 29 : (daysInMonthCache[month - 1] ?? 31); return day <= maxDays; }, }, time: { pattern: "##:##", transform: (value) => value.replace(REGEX_CACHE.nonDigits, ""), validate: (value) => { const cleaned = value.replace(REGEX_CACHE.nonDigits, ""); if (!REGEX_CACHE.time.test(cleaned)) return false; const hours = parseInt(cleaned.substring(0, 2), 10); const minutes = parseInt(cleaned.substring(2, 4), 10); return hours <= 23 && minutes <= 59; }, }, creditCard: { pattern: "#### #### #### ####", transform: (value) => value.replace(REGEX_CACHE.nonDigits, ""), validate: (value) => { const cleaned = value.replace(REGEX_CACHE.nonDigits, ""); if (!REGEX_CACHE.creditCard.test(cleaned)) return false; let sum = 0; let isEven = false; for (let i = cleaned.length - 1; i >= 0; i--) { const digitChar = cleaned[i]; if (!digitChar) continue; let digit = parseInt(digitChar, 10); if (isEven) { digit = 2; if (digit > 9) { digit -= 9; } } sum += digit; isEven = !isEven; } return sum % 10 === 0; }, }, creditCardExpiry: { pattern: "##/##", transform: (value) => value.replace(REGEX_CACHE.nonDigits, ""), validate: (value) => { const cleaned = value.replace(REGEX_CACHE.nonDigits, ""); if (!REGEX_CACHE.creditCardExpiry.test(cleaned)) return false; const month = parseInt(cleaned.substring(0, 2), 10); const year = parseInt(cleaned.substring(2, 4), 10); if (month < 1 || month > 12) return false; const now = new Date(); const currentYear = now.getFullYear(); const currentMonth = now.getMonth() + 1; const fullYear = year <= 75 ? 2000 + year : 1900 + year; if ( fullYear < currentYear || (fullYear === currentYear && month < currentMonth) ) { return false; } const maxYear = currentYear + 50; if (fullYear > maxYear) { return false; } return true; }, }, zipCode: { pattern: "#####", transform: (value) => value.replace(REGEX_CACHE.nonDigits, ""), validate: (value) => REGEX_CACHE.zipCode.test(value.replace(REGEX_CACHE.nonDigits, "")), }, zipCodeExtended: { pattern: "#####-####", transform: (value) => value.replace(REGEX_CACHE.nonDigits, ""), validate: (value) => REGEX_CACHE.zipCodeExtended.test( value.replace(REGEX_CACHE.nonDigits, ""), ), }, currency: { pattern: "$###,###.##", transform: ( value, { currency = DEFAULT_CURRENCY, locale = DEFAULT_LOCALE } = {}, ) => { let localeDecimalSeparator = "."; try { const formatter = getCachedFormatter(locale, { currency, minimumFractionDigits: 0, maximumFractionDigits: 2, }); const parts = formatter.formatToParts(1234.5); const decimalPart = parts.find((part) => part.type === "decimal"); if (decimalPart) localeDecimalSeparator = decimalPart.value; } catch { // Keep defaults } const cleaned = value.replace(REGEX_CACHE.nonCurrencyChars, ""); const dotIndex = cleaned.indexOf("."); const commaIndex = cleaned.indexOf(","); let hasDecimalSeparator = false; let decimalIndex = -1; if (localeDecimalSeparator === ",") { const lastCommaIndex = cleaned.lastIndexOf(","); if (lastCommaIndex !== -1) { const afterComma = cleaned.substring(lastCommaIndex + 1); if (afterComma.length <= 2 && /^\d$/.test(afterComma)) { hasDecimalSeparator = true; decimalIndex = lastCommaIndex; } } if (!hasDecimalSeparator && dotIndex !== -1) { const afterDot = cleaned.substring(dotIndex + 1); if (afterDot.length <= 2 && /^\d$/.test(afterDot)) { hasDecimalSeparator = true; decimalIndex = dotIndex; } } if (!hasDecimalSeparator && cleaned.length >= 4) { const match = cleaned.match(/^(\d+)\.(\d{3})(\d{1,2})$/); if (match) { const [, beforeDot, thousandsPart, decimalPart] = match; const integerPart = (beforeDot ?? "") + (thousandsPart ?? ""); const result = `${integerPart}.${decimalPart}`; return result; } } } else { const lastDotIndex = cleaned.lastIndexOf("."); if (lastDotIndex !== -1) { const afterDot = cleaned.substring(lastDotIndex + 1); if (afterDot.length <= 2 && /^\d$/.test(afterDot)) { hasDecimalSeparator = true; decimalIndex = lastDotIndex; } } if (!hasDecimalSeparator && commaIndex !== -1) { const afterComma = cleaned.substring(commaIndex + 1); const looksLikeThousands = commaIndex <= 3 && afterComma.length >= 3; if ( !looksLikeThousands && afterComma.length <= 2 && /^\d$/.test(afterComma) ) { hasDecimalSeparator = true; decimalIndex = commaIndex; } } } if (hasDecimalSeparator && decimalIndex !== -1) { const beforeDecimal = cleaned .substring(0, decimalIndex) .replace(/[.,]/g, ""); const afterDecimal = cleaned .substring(decimalIndex + 1) .replace(/[.,]/g, ""); if (afterDecimal === "") { const result = `${beforeDecimal}.`; return result; } const result = `${beforeDecimal}.${afterDecimal.substring(0, 2)}`; return result; } const digitsOnly = cleaned.replace(/[.,]/g, ""); return digitsOnly; }, validate: (value) => { if (!REGEX_CACHE.currencyValidation.test(value)) return false; const num = parseFloat(value); return !Number.isNaN(num) && num >= 0; }, }, percentage: { pattern: "##.##%", transform: (value) => { const cleaned = value.replace(REGEX_CACHE.percentageChars, ""); const parts = cleaned.split("."); if (parts.length > 2) { return `${parts[0]}.${parts.slice(1).join("")}`; } if (parts[1] && parts[1].length > 2) { return `${parts[0]}.${parts[1].substring(0, 2)}`; } return cleaned; }, validate: (value, opts = {}) => { const num = parseFloat(value); const min = opts.min ?? 0; const max = opts.max ?? 100; return !Number.isNaN(num) && num >= min && num <= max; }, }, licensePlate: { pattern: "###-###", transform: (value) => value.replace(REGEX_CACHE.nonAlphaNumeric, "").toUpperCase(), validate: (value) => REGEX_CACHE.licensePlate.test(value), }, ipv4: { pattern: "###.###.###.###", transform: (value) => value.replace(REGEX_CACHE.nonNumericDot, ""), validate: (value) => { if (value.includes(".")) { const segments = value.split("."); if (segments.length > 4) return false; return segments.every((segment) => { if (segment === "") return true; if (!REGEX_CACHE.ipv4Segment.test(segment)) return false; const num = parseInt(segment, 10); return num <= 255; }); } else { if (!REGEX_CACHE.digitsOnly.test(value)) return false; if (value.length > 12) return false; const chunks = []; for (let i = 0; i < value.length; i += 3) { chunks.push(value.substring(i, i + 3)); } if (chunks.length > 4) return false; return chunks.every((chunk) => { const num = parseInt(chunk, 10); return num >= 0 && num <= 255; }); } }, }, macAddress: { pattern: "##:##:##:##:##:##", transform: (value) => value.replace(REGEX_CACHE.nonAlphaNumeric, "").toUpperCase(), validate: (value) => REGEX_CACHE.macAddress.test(value), }, isbn: { pattern: "###-#-###-#####-#", transform: (value) => value.replace(REGEX_CACHE.nonDigits, ""), validate: (value) => REGEX_CACHE.isbn.test(value.replace(REGEX_CACHE.nonDigits, "")), }, ein: { pattern: "##-#######", transform: (value) => value.replace(REGEX_CACHE.nonDigits, ""), validate: (value) => REGEX_CACHE.ein.test(value.replace(REGEX_CACHE.nonDigits, "")), }, }; function applyMask(opts: { value: string; pattern: string; currency?: string; locale?: string; mask?: MaskPatternKey | MaskPattern; }): string { const { value, pattern, currency, locale, mask } = opts; const cleanValue = value; if (pattern.includes("$") || pattern.includes("€") || mask === "currency") { return applyCurrencyMask({ value: cleanValue, currency: currency ?? DEFAULT_CURRENCY, locale: locale ?? DEFAULT_LOCALE, }); } if (pattern.includes("%")) { return applyPercentageMask(cleanValue); } if (mask === "ipv4") { return cleanValue; } const maskedChars: string[] = []; let valueIndex = 0; for (let i = 0; i < pattern.length && valueIndex < cleanValue.length; i++) { const patternChar = pattern[i]; const valueChar = cleanValue[valueIndex]; if (patternChar === "#" && valueChar) { maskedChars.push(valueChar); valueIndex++; } else if (patternChar) { maskedChars.push(patternChar); } } return maskedChars.join(""); } function applyCurrencyMask(opts: { value: string; currency?: string; locale?: string; }): string { const { value, currency = DEFAULT_CURRENCY, locale = DEFAULT_LOCALE } = opts; if (!value) return ""; const { currency: currencySymbol, decimal: decimalSeparator, group: groupSeparator, } = getCachedCurrencySymbols({ locale, currency }); const normalizedValue = value .replace( new RegExp( `\\${groupSeparator.replace(/[.+?^${}()|[\]\\]/g, "\\$&")}`, "g", ), "", ) .replace(decimalSeparator, "."); const parts = normalizedValue.split("."); const integerPart = parts[0] ?? ""; const fractionalPart = parts[1] ?? ""; if (!integerPart && !fractionalPart) return ""; const intValue = integerPart ?? "0"; const fracValue = fractionalPart.slice(0, 2); const num = Number(`${intValue}.${fracValue ?? ""}`); if (Number.isNaN(num)) { const cleanedDigits = value.replace(/[^\d]/g, ""); if (!cleanedDigits) return ""; return `${currencySymbol}${cleanedDigits}`; } const hasExplicitDecimal = value.includes(".") || value.includes(decimalSeparator); try { const formatter = getCachedFormatter(locale, { currency, minimumFractionDigits: fracValue ? fracValue.length : 0, maximumFractionDigits: 2, }); const result = formatter.format(num); if (hasExplicitDecimal && !fracValue) { if (result.match(/^[^\d\s]+/)) { const finalResult = result.replace(/(\d)$/, `$1${decimalSeparator}`); return finalResult; } else { const finalResult = result.replace( /(\d)(\s)([^\d\s]+)$/, `$1${decimalSeparator}$2$3`, ); return finalResult; } } return result; } catch { const formattedInt = intValue.replace( /\B(?=(\d{3})+(?!\d))/g, groupSeparator, ); let result = `${currencySymbol}${formattedInt}`; if (hasExplicitDecimal) { result += `${decimalSeparator}${fracValue}`; } return result; } } function applyPercentageMask(value: string): string { if (!value) return ""; const parts = value.split("."); let result = parts[0] ?? "0"; if (value.includes(".")) { result += `.${(parts[1] ?? "").substring(0, 2)}`; } return `${result}%`; } function getUnmaskedValue(opts: { value: string; currency?: string; locale?: string; transform?: (value: string, opts?: TransformOptions) => string; }): string { const { value, transform, currency, locale } = opts; return transform ? transform(value, { currency, locale }) : value.replace(REGEX_CACHE.nonDigits, ""); } function toUnmaskedIndex(opts: { masked: string; pattern: string; caret: number; }): number { const { masked, pattern, caret } = opts; let idx = 0; for (let i = 0; i < caret && i < masked.length && i < pattern.length; i++) { if (pattern[i] === "#") { idx++; } } return idx; } function fromUnmaskedIndex(opts: { masked: string; pattern: string; unmaskedIndex: number; }): number { const { masked, pattern, unmaskedIndex } = opts; let seen = 0; for (let i = 0; i < masked.length && i < pattern.length; i++) { if (pattern[i] === "#") { seen++; if (seen === unmaskedIndex) { return i + 1; } } } return masked.length; } function getCurrencyCaretPosition(opts: { newValue: string; mask: MaskPatternKey | MaskPattern | undefined; transformOpts: TransformOptions; oldCursorPosition?: number; oldValue?: string; previousUnmasked?: string; }): number { const { newValue, mask, transformOpts, oldCursorPosition, oldValue, previousUnmasked, } = opts; if ( oldCursorPosition !== undefined && oldValue && previousUnmasked !== undefined ) { if (oldCursorPosition < oldValue.length) { const digitsBeforeCursor = oldValue .substring(0, oldCursorPosition) .replace(/\D/g, "").length; let digitCount = 0; for (let i = 0; i < newValue.length; i++) { if (/\d/.test(newValue[i] ?? "")) { digitCount++; if (digitCount === digitsBeforeCursor) { return i + 1; } } } } } if (mask === "currency") { const currencyAtEnd = isCurrencyAtEnd(transformOpts); if (currencyAtEnd) { const match = newValue.match(/(\d)\s([^\d\s]+)$/); if (match?.[1]) { return newValue.lastIndexOf(match[1]) + 1; } else { return newValue.length; } } else { return newValue.length; } } else { return newValue.length; } } function getPatternCaretPosition(opts: { newValue: string; maskPattern: MaskPattern; currentUnmasked: string; oldCursorPosition?: number; oldValue?: string; previousUnmasked?: string; }): number { const { newValue, maskPattern, currentUnmasked, oldCursorPosition, oldValue, previousUnmasked, } = opts; let position = 0; let unmaskedCount = 0; if ( oldCursorPosition !== undefined && oldValue && previousUnmasked !== undefined ) { const oldUnmaskedIndex = toUnmaskedIndex({ masked: oldValue, pattern: maskPattern.pattern, caret: oldCursorPosition, }); if (oldCursorPosition < oldValue.length) { const targetUnmaskedIndex = Math.min( oldUnmaskedIndex, currentUnmasked.length, ); for ( let i = 0; i < maskPattern.pattern.length && i < newValue.length; i++ ) { if (maskPattern.pattern[i] === "#") { unmaskedCount++; if (unmaskedCount <= targetUnmaskedIndex) { position = i + 1; } } } return position; } } for (let i = 0; i < maskPattern.pattern.length && i < newValue.length; i++) { if (maskPattern.pattern[i] === "#") { unmaskedCount++; if (unmaskedCount <= currentUnmasked.length) { position = i + 1; } } } return position; } type InputElement = React.ComponentRef<"input">; interface MaskInputProps extends React.ComponentProps<"input"> { value?: string; defaultValue?: string; onValueChange?: (maskedValue: string, unmaskedValue: string) => void; onValidate?: (isValid: boolean, unmaskedValue: string) => void; validationMode?: "onChange" | "onBlur" | "onSubmit" | "onTouched" | "all"; mask?: MaskPatternKey | MaskPattern; maskPlaceholder?: string; currency?: string; locale?: string; asChild?: boolean; invalid?: boolean; withoutMask?: boolean; } function MaskInput(props: MaskInputProps) { const { value: valueProp, defaultValue, onValueChange: onValueChangeProp, onValidate, onBlur: onBlurProp, onFocus: onFocusProp, onKeyDown: onKeyDownProp, onPaste: onPasteProp, onCompositionStart: onCompositionStartProp, onCompositionEnd: onCompositionEndProp, validationMode = "onChange", mask, maskPlaceholder, currency = DEFAULT_CURRENCY, locale = DEFAULT_LOCALE, placeholder, inputMode, min, max, maxLength, asChild = false, disabled = false, invalid = false, readOnly = false, required = false, withoutMask = false, className, ref, ...inputProps } = props; const [internalValue, setInternalValue] = React.useState(defaultValue ?? ""); const [focused, setFocused] = React.useState(false); const [composing, setComposing] = React.useState(false); const [touched, setTouched] = React.useState(false); const inputRef = React.useRef(null); const composedRef = useComposedRefs(ref, inputRef); const isControlled = valueProp !== undefined; const value = isControlled ? valueProp : internalValue; const maskPattern = React.useMemo(() => { if (typeof mask === "string") { return MASK_PATTERNS[mask]; } return mask; }, [mask]); const transformOpts = React.useMemo( () => ({ currency, locale, }), [currency, locale], ); const placeholderValue = React.useMemo(() => { if (withoutMask) return placeholder; if (placeholder && maskPlaceholder) { return focused ? maskPlaceholder : placeholder; } if (maskPlaceholder) { return focused ? maskPlaceholder : undefined; } return placeholder; }, [placeholder, maskPlaceholder, focused, withoutMask]); const displayValue = React.useMemo(() => { if (withoutMask || !maskPattern || !value) return value ?? ""; const unmasked = getUnmaskedValue({ value, transform: maskPattern.transform, ...transformOpts, }); return applyMask({ value: unmasked, pattern: maskPattern.pattern, ...transformOpts, mask, }); }, [value, maskPattern, withoutMask, transformOpts, mask]); const tokenCount = React.useMemo(() => { if (!maskPattern || CURRENCY_PERCENTAGE_SYMBOLS.test(maskPattern.pattern)) return undefined; return maskPattern.pattern.match(REGEX_CACHE.hashPattern)?.length ?? 0; }, [maskPattern]); const calculatedMaxLength = tokenCount ? maskPattern?.pattern.length : maxLength; const calculatedInputMode = React.useMemo(() => { if (inputMode) return inputMode; if (!maskPattern) return undefined; if (mask === "currency" || mask === "percentage" || mask === "ipv4") { return "decimal"; } if (typeof mask === "string" && NUMERIC_MASK_PATTERNS.test(mask)) { return "numeric"; } return undefined; }, [maskPattern, mask, inputMode]); const shouldValidate = React.useCallback( (trigger: "change" | "blur") => { if (!onValidate || !maskPattern?.validate) return false; switch (validationMode) { case "onChange": return trigger === "change"; case "onBlur": return trigger === "blur"; case "onSubmit": return false; case "onTouched": return touched ? trigger === "change" : trigger === "blur"; case "all": return true; default: return trigger === "change"; } }, [onValidate, maskPattern, validationMode, touched], ); const validationOpts = React.useMemo( () => ({ min: typeof min === "string" ? parseFloat(min) : min, max: typeof max === "string" ? parseFloat(max) : max, }), [min, max], ); const onInputValidate = React.useCallback( (unmaskedValue: string) => { if (onValidate && maskPattern?.validate) { const isValid = maskPattern.validate(unmaskedValue, validationOpts); onValidate(isValid, unmaskedValue); } }, [onValidate, maskPattern?.validate, validationOpts], ); const onValueChange = React.useCallback( (event: React.ChangeEvent) => { const inputValue = event.target.value; let newValue = inputValue; let unmaskedValue = inputValue; if (composing) { if (!isControlled) setInternalValue(inputValue); return; } if (withoutMask || !maskPattern) { if (!isControlled) setInternalValue(inputValue); if (shouldValidate("change")) onValidate?.(true, inputValue); onValueChangeProp?.(inputValue, inputValue); return; } if (maskPattern) { unmaskedValue = getUnmaskedValue({ value: inputValue, transform: maskPattern.transform, ...transformOpts, }); newValue = applyMask({ value: unmaskedValue, pattern: maskPattern.pattern, ...transformOpts, mask, }); if (inputRef.current && newValue !== inputValue) { const inputElement = inputRef.current; if (!(inputElement instanceof HTMLInputElement)) return; const oldCursorPosition = inputElement.selectionStart ?? 0; inputElement.value = newValue; const currentUnmasked = getUnmaskedValue({ value: newValue, transform: maskPattern.transform, ...transformOpts, }); let newCursorPosition: number; const previousUnmasked = getUnmaskedValue({ value, transform: maskPattern.transform, ...transformOpts, }); if (CURRENCY_PERCENTAGE_SYMBOLS.test(maskPattern.pattern)) { newCursorPosition = getCurrencyCaretPosition({ newValue, mask, transformOpts, oldCursorPosition, oldValue: inputValue, previousUnmasked, }); } else { newCursorPosition = getPatternCaretPosition({ newValue, maskPattern, currentUnmasked, oldCursorPosition, oldValue: inputValue, previousUnmasked, }); } if (isCurrencyMask({ mask, pattern: maskPattern.pattern })) { if (mask === "currency") { const currencyAtEnd = isCurrencyAtEnd(transformOpts); if (!currencyAtEnd) { newCursorPosition = Math.max(1, newCursorPosition); } } else { newCursorPosition = Math.max(1, newCursorPosition); } } else if (maskPattern.pattern.includes("%")) { newCursorPosition = Math.min( newValue.length - 1, newCursorPosition, ); } newCursorPosition = Math.min(newCursorPosition, newValue.length); inputElement.setSelectionRange(newCursorPosition, newCursorPosition); } } if (!isControlled) { setInternalValue(newValue); } if (shouldValidate("change")) { onInputValidate(unmaskedValue); } onValueChangeProp?.(newValue, unmaskedValue); }, [ maskPattern, isControlled, onValueChangeProp, onValidate, onInputValidate, composing, shouldValidate, withoutMask, transformOpts, mask, value, ], ); const onFocus = React.useCallback( (event: React.FocusEvent) => { onFocusProp?.(event); if (event.defaultPrevented) return; setFocused(true); }, [onFocusProp], ); const onBlur = React.useCallback( (event: React.FocusEvent) => { onBlurProp?.(event); if (event.defaultPrevented) return; setFocused(false); if (!touched) { setTouched(true); } if (shouldValidate("blur")) { const currentValue = event.target.value; const unmaskedValue = maskPattern ? getUnmaskedValue({ value: currentValue, transform: maskPattern.transform, ...transformOpts, }) : currentValue; onInputValidate(unmaskedValue); } }, [ onBlurProp, touched, shouldValidate, onInputValidate, maskPattern, transformOpts, ], ); const onCompositionStart = React.useCallback( (event: React.CompositionEvent) => { onCompositionStartProp?.(event); if (event.defaultPrevented) return; setComposing(true); }, [onCompositionStartProp], ); const onCompositionEnd = React.useCallback( (event: React.CompositionEvent) => { onCompositionEndProp?.(event); if (event.defaultPrevented) return; setComposing(false); const inputElement = inputRef.current; if (!inputElement) return; if (!(inputElement instanceof HTMLInputElement)) return; const inputValue = inputElement.value; if (!maskPattern || withoutMask) { if (!isControlled) setInternalValue(inputValue); if (shouldValidate("change")) onValidate?.(true, inputValue); onValueChangeProp?.(inputValue, inputValue); return; } const unmasked = getUnmaskedValue({ value: inputValue, transform: maskPattern.transform, ...transformOpts, }); const masked = applyMask({ value: unmasked, pattern: maskPattern.pattern, ...transformOpts, mask, }); if (!isControlled) setInternalValue(masked); if (shouldValidate("change")) onInputValidate(unmasked); onValueChangeProp?.(masked, unmasked); }, [ onCompositionEndProp, maskPattern, withoutMask, isControlled, shouldValidate, onValidate, onValueChangeProp, transformOpts, mask, onInputValidate, ], ); const onPaste = React.useCallback( (event: React.ClipboardEvent) => { onPasteProp?.(event); if (event.defaultPrevented) return; if (withoutMask || !maskPattern) return; if (mask === "ipv4") return; const target = event.target as InputElement; if (!(target instanceof HTMLInputElement)) return; const pastedData = event.clipboardData.getData("text"); if (!pastedData) return; event.preventDefault(); const currentValue = target.value; const selectionStart = target.selectionStart ?? 0; const selectionEnd = target.selectionEnd ?? 0; const beforeSelection = currentValue.slice(0, selectionStart); const afterSelection = currentValue.slice(selectionEnd); const newInputValue = beforeSelection + pastedData + afterSelection; const unmasked = getUnmaskedValue({ value: newInputValue, transform: maskPattern.transform, ...transformOpts, }); const newMaskedValue = applyMask({ value: unmasked, pattern: maskPattern.pattern, ...transformOpts, mask, }); target.value = newMaskedValue; if (isCurrencyMask({ mask, pattern: maskPattern.pattern })) { const currencyAtEnd = isCurrencyAtEnd(transformOpts); const caret = currencyAtEnd ? newMaskedValue.search(/\s[^\d\s]+$/) : newMaskedValue.length; target.setSelectionRange(caret, caret); return; } if (maskPattern.pattern.includes("%")) { target.setSelectionRange( newMaskedValue.length - 1, newMaskedValue.length - 1, ); return; } let newCursorPosition = newMaskedValue.length; try { const unmaskedCount = unmasked.length; let position = 0; let count = 0; for ( let i = 0; i < maskPattern.pattern.length && i < newMaskedValue.length; i++ ) { if (maskPattern.pattern[i] === "#") { count++; if (count <= unmaskedCount) { position = i + 1; } } } newCursorPosition = position; } catch { // fallback to end } target.setSelectionRange(newCursorPosition, newCursorPosition); if (!isControlled) setInternalValue(newMaskedValue); if (shouldValidate("change")) onInputValidate(unmasked); onValueChangeProp?.(newMaskedValue, unmasked); }, [ onPasteProp, withoutMask, maskPattern, mask, transformOpts, isControlled, shouldValidate, onInputValidate, onValueChangeProp, ], ); const onKeyDown = React.useCallback( (event: React.KeyboardEvent) => { onKeyDownProp?.(event); if (event.defaultPrevented) return; if (withoutMask || !maskPattern) return; if (mask === "ipv4") return; if (event.key === "Backspace") { const target = event.target as InputElement; if (!(target instanceof HTMLInputElement)) return; const cursorPosition = target.selectionStart ?? 0; const selectionEnd = target.selectionEnd ?? 0; const currentValue = target.value; if ( mask === "currency" || mask === "percentage" || maskPattern.pattern.includes("$") || maskPattern.pattern.includes("€") || maskPattern.pattern.includes("%") ) { return; } if (cursorPosition !== selectionEnd) { return; } if (cursorPosition > 0) { const charBeforeCursor = currentValue[cursorPosition - 1]; if (charBeforeCursor) { event.preventDefault(); const unmaskedIndex = toUnmaskedIndex({ masked: currentValue, pattern: maskPattern.pattern, caret: cursorPosition, }); if (unmaskedIndex > 0) { const currentUnmasked = getUnmaskedValue({ value: currentValue, transform: maskPattern.transform, ...transformOpts, }); const nextUnmasked = currentUnmasked.slice(0, unmaskedIndex - 1) + currentUnmasked.slice(unmaskedIndex); const nextMasked = applyMask({ value: nextUnmasked, pattern: maskPattern.pattern, ...transformOpts, mask, }); target.value = nextMasked; const nextCaret = fromUnmaskedIndex({ masked: nextMasked, pattern: maskPattern.pattern, unmaskedIndex: unmaskedIndex - 1, }); target.setSelectionRange(nextCaret, nextCaret); onValueChangeProp?.(nextMasked, nextUnmasked); } return; } } } if (event.key === "Delete") { const target = event.target as InputElement; if (!(target instanceof HTMLInputElement)) return; const cursorPosition = target.selectionStart ?? 0; const selectionEnd = target.selectionEnd ?? 0; const currentValue = target.value; if ( mask === "currency" || mask === "percentage" || maskPattern.pattern.includes("$") || maskPattern.pattern.includes("€") || maskPattern.pattern.includes("%") ) { return; } if (cursorPosition !== selectionEnd) { return; } if (cursorPosition < currentValue.length) { const charAtCursor = currentValue[cursorPosition]; if (charAtCursor) { event.preventDefault(); const unmaskedIndex = toUnmaskedIndex({ masked: currentValue, pattern: maskPattern.pattern, caret: cursorPosition, }); const currentUnmasked = getUnmaskedValue({ value: currentValue, transform: maskPattern.transform, ...transformOpts, }); if (unmaskedIndex < currentUnmasked.length) { const nextUnmasked = currentUnmasked.slice(0, unmaskedIndex) + currentUnmasked.slice(unmaskedIndex + 1); const nextMasked = applyMask({ value: nextUnmasked, pattern: maskPattern.pattern, ...transformOpts, mask, }); target.value = nextMasked; const nextCaret = fromUnmaskedIndex({ masked: nextMasked, pattern: maskPattern.pattern, unmaskedIndex: unmaskedIndex, }); target.setSelectionRange(nextCaret, nextCaret); onValueChangeProp?.(nextMasked, nextUnmasked); } return; } } } }, [ maskPattern, onKeyDownProp, onValueChangeProp, transformOpts, mask, withoutMask, ], ); const InputPrimitive = asChild ? SlotPrimitive.Slot : "input"; return ( ); } export { applyCurrencyMask, applyMask, applyPercentageMask, fromUnmaskedIndex, getUnmaskedValue, MASK_PATTERNS, MaskInput, type MaskInputProps, type MaskPattern, toUnmaskedIndex, }; ``` ## Usage [#usage] ### BuiltInPatterns [#builtinpatterns] ```tsx export const BuiltInPatterns = () => { const [values, setValues] = React.useState({ phone: "", date: "", currency: "", euro: "", creditCard: "", percentage: "", }); const setField = React.useCallback( (field: keyof typeof values) => (masked: string) => { setValues((prev) => ({ ...prev, [field]: masked })); }, [], ); return (

Phone

Date

Currency (USD)

Currency (EUR)

Credit card

Percentage

); }; ``` ### CustomPattern [#custompattern] ```tsx export const CustomPattern = () => { const [value, setValue] = React.useState(""); const licensePlate: MaskPattern = { pattern: "###-####", transform: (input) => input.replace(/[^A-Z0-9]/gi, "").toUpperCase(), validate: (input) => input.replace(/[^A-Z0-9]/gi, "").length === 7, }; return (
License plate setValue(masked)} />
Custom alphanumeric pattern

); }; ``` ### ValidationModes [#validationmodes] ```tsx export const ValidationModes = () => { const [value, setValue] = React.useState(""); const [valid, setValid] = React.useState(null); return (
SSN (validate on blur) setValue(masked)} onValidate={(isValid) => setValid(isValid)} invalid={valid === false} />
{valid === null ? "Blur to validate" : valid ? "Valid SSN" : "Invalid SSN"}

); }; ``` ### CardInformation [#cardinformation] ```tsx export const CardInformation = () => { const [card, setCard] = React.useState(""); const [expiry, setExpiry] = React.useState(""); return (

Card number setCard(masked)} />

Expiry setExpiry(masked)} />

); }; ``` # Masonry (/docs/components/masonry) ## Preview [#preview] ```tsx import { Masonry, MasonryItem } from "@/components/ui/Masonry"; export function MasonryDemo() { return (
Color

Typography runs taller

Space

Motion
) } ``` ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/masonry ``` ### Manual [#manual] Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` Copy and paste the Masonry component into your `components/ui/Masonry.tsx` file. ```tsx "use client"; import * as React from "react"; import { cn } from "@/utils/class-names"; function Masonry({ className, ...props }: React.ComponentProps<"div">) { return (
); } function MasonryItem({ className, ...props }: React.ComponentProps<"div">) { return (
); } export { Masonry, MasonryItem }; ``` # Media Player (/docs/components/media-player) ## Preview [#preview] ```tsx import { useEffect, useState } from "react"; import { MediaPlayer } from "@/components/ui/MediaPlayer"; export function MediaPlayerDemo() { const [src, setSrc] = useState(); useEffect(() => { const sampleRate = 8000; const samples = 800; const buffer = new ArrayBuffer(44 + samples * 2); const view = new DataView(buffer); const write = (offset: number, text: string) => { for (let index = 0; index < text.length; index += 1) { view.setUint8(offset + index, text.charCodeAt(index)); } }; write(0, "RIFF"); view.setUint32(4, 36 + samples * 2, true); write(8, "WAVE"); write(12, "fmt "); view.setUint32(16, 16, true); view.setUint16(20, 1, true); view.setUint16(22, 1, true); view.setUint32(24, sampleRate, true); view.setUint32(28, sampleRate * 2, true); view.setUint16(32, 2, true); view.setUint16(34, 16, true); write(36, "data"); view.setUint32(40, samples * 2, true); for (let index = 0; index < samples; index += 1) { const sample = Math.sin((2 * Math.PI * 440 * index) / sampleRate) * 0.2; view.setInt16(44 + index * 2, Math.round(sample * 0x7fff), true); } const url = URL.createObjectURL(new Blob([buffer], { type: "audio/wav" })); setSrc(url); return () => URL.revokeObjectURL(url); }, []); return ; } ``` ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/media-player ``` ### Manual [#manual] Copy and paste the button component into your `components/ui/Button.tsx` file. ```tsx /** * @description Displays a button or a component that looks like a button. / import as React from "react"; import { Slot } from "@radix-ui/react-slot"; import { cva, type VariantProps } from "class-variance-authority"; import { cn } from "@/utils/class-names"; import { Spinner } from "@/components/ui/Spinner"; const buttonVariants = cva("button", { variants: { variant: { default: "button-fill", fill: "button-fill", pill: "button-pill border border-gray-6 text-gray-11 bg-gray-2 hover:bg-gray-3", link: "button-link", menu: "button-menu", }, size: { default: "h-4", xs: "h-2.5", sm: "h-3", md: "h-4", lg: "h-5", xl: "h-6", icon: "w-3 h-3 p-0", "icon-md": "w-4 h-4 p-0", }, }, defaultVariants: { variant: "default", size: "default", }, }); interface ButtonProps extends React.ComponentProps<"button">, VariantProps { asChild?: boolean; isDisabled?: boolean; isLoading?: boolean; isLoadingText?: string | React.ReactNode; mode?: VariantProps["variant"]; label?: string | React.ReactNode; } const Button = React.forwardRef( (props: ButtonProps, ref) => { const { className, variant, mode, size, asChild = false, isDisabled, isLoading, isLoadingText, children, label, ...rest } = props; const Comp = asChild ? Slot : "button"; const disabled = isDisabled || isLoading || props.disabled; const effectiveVariant = variant ?? mode; return ( {asChild ? ( children ) : ( <> {isLoading && isLoadingText ? ( isLoadingText ) : ( <> {isLoading ? : null} {label} {children} )} )} ); } ); Button.displayName = "Button"; export { Button, buttonVariants }; export type { ButtonProps }; export default Button; ``` Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` Copy and paste the MediaPlayer component into your `components/ui/MediaPlayer.tsx` file. ```tsx "use client"; import * as React from "react"; import { cn } from "@/utils/class-names"; import { Button } from "@/components/ui/Button"; function formatTime(seconds: number) { if (!Number.isFinite(seconds) || seconds < 0) return "0:00"; const whole = Math.floor(seconds); const minutes = Math.floor(whole / 60); const remain = whole % 60; return `${minutes}:${remain.toString().padStart(2, "0")}`; } function MediaPlayer({ className, src, label = "Media player", }: { className?: string; src?: string; label?: string; }) { const media = React.useRef(null); const [playing, setPlaying] = React.useState(false); const [muted, setMuted] = React.useState(false); const [time, setTime] = React.useState(0); const [duration, setDuration] = React.useState(0); const toggle = () => { const node = media.current; if (!node) return; if (node.paused) void node.play(); else node.pause(); }; return (

); } export { MediaPlayer }; ``` # Mention (/docs/components/mention) ## Preview [#preview] ```tsx import * as React from "react"; import { Mention, MentionContent, MentionInput, MentionItem, MentionLabel, MentionPortal, } from "@/components/ui/Mention"; import { Textarea } from "@/components/ui/Textarea"; export function MentionDemo() { return ( Mention users </MentionInput> <MentionPortal> <MentionContent> {users.map((user) => ( <MentionItem key={user.id} value={user.name} className="flex-col items-start" > <span className="text-sm">{user.name}</span> <span className="text-xs text-gray-11">{user.email}</span> </MentionItem> ))} </MentionContent> </MentionPortal> </Mention> ); } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/mention ``` ### Manual [#manual] <Steps> <Step> Install the following dependencies: ```bash pnpm install @diceui/mention ``` </Step> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the Mention component into your `components/ui/Mention.tsx` file. ```tsx "use client"; /** * @description Adds accessible, trigger-based mentions to a text input. / import as React from "react"; import * as MentionPrimitive from "@diceui/mention"; import { cn } from "@/utils/class-names"; function Mention({ className, ...props }: React.ComponentProps<typeof MentionPrimitive.Root>) { return ( <MentionPrimitive.Root data-slot="mention" className={cn( ":data-tag:rounded-sm :data-tag:bg-accent-3 :data-tag:px-0.5 :data-tag:text-accent-12", className, )} {...props} /> ); } function MentionLabel({ className, ...props }: React.ComponentProps<typeof MentionPrimitive.Label>) { return ( <MentionPrimitive.Label data-slot="mention-label" className={cn( "mb-0.5 block text-sm font-semibold text-gray-12 peer-disabled:cursor-not-allowed peer-disabled:opacity-50", className, )} {...props} /> ); } function MentionInput({ className, ...props }: React.ComponentProps<typeof MentionPrimitive.Input>) { return ( <MentionPrimitive.Input data-slot="mention-input" className={cn( "flex min-h-4 w-full rounded-md border border-gray-7 bg-gray-1 px-1 py-0.5 text-gray-12 placeholder:text-gray-11 focus-visible:border-gray-8 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-gray-8 disabled:cursor-not-allowed disabled:opacity-50", className, )} {...props} /> ); } function MentionPortal({ ...props }: React.ComponentProps<typeof MentionPrimitive.Portal>) { return <MentionPrimitive.Portal data-slot="mention-portal" {...props} />; } function MentionContent({ className, ...props }: React.ComponentProps<typeof MentionPrimitive.Content>) { return ( <MentionPrimitive.Content data-slot="mention-content" className={cn( "z-50 min-w-(--dice-anchor-width) origin-(--dice-transform-origin) overflow-hidden rounded-md border border-gray-7 bg-gray-1 p-0.5 text-gray-12 shadow-md data-[state=closed]:animate-mention-hide data-[state=open]:animate-mention-show", className, )} {...props} /> ); } function MentionItem({ className, ...props }: React.ComponentProps<typeof MentionPrimitive.Item>) { return ( <MentionPrimitive.Item data-slot="mention-item" className={cn( "relative flex w-full cursor-default select-none items-center gap-0.5 rounded-sm px-1 py-0.5 text-sm outline-none data-disabled:pointer-events-none data-disabled:opacity-50 data-highlighted:bg-accent-3 data-highlighted:text-accent-12", className, )} {...props} /> ); } export { Mention, MentionContent, MentionInput, MentionItem, MentionLabel, MentionPortal, }; ``` </Step> </Steps> ## Usage [#usage] ### CustomTrigger [#customtrigger] ```tsx export const CustomTrigger = () => { return ( <Mention trigger="#" className="smosh"> <MentionLabel>Mention a topic</MentionLabel> <MentionInput placeholder="Type # to mention a topic…" asChild> <Textarea /> </MentionInput> <MentionPortal> <MentionContent> {users.map((user) => ( <MentionItem key={user.id} value={user.name}> {user.name} </MentionItem> ))} </MentionContent> </MentionPortal> </Mention> ); }; ``` ### CustomFilter [#customfilter] ```tsx export const CustomFilter = () => { const [value, setValue] = React.useState<string[]>([]); const [inputValue, setInputValue] = React.useState(""); const filterCommands = React.useCallback( (options: string[], term: string) => options.filter((option) => option.toLowerCase().startsWith(term.toLowerCase()), ), [], ); return ( <Mention className="smosh" inputValue={inputValue} onFilter={filterCommands} onInputValueChange={setInputValue} onValueChange={setValue} trigger="/" value={value} > <MentionLabel>Run a command</MentionLabel> <MentionInput placeholder="Type / to use a command…" asChild> <Textarea /> </MentionInput> <MentionPortal> <MentionContent> {commands.map((command) => ( <MentionItem key={command.name} label={command.name} value={command.name} className="flex-col items-start" > <span className="font-mono text-sm">{command.name}</span> <span className="text-xs text-gray-11"> {command.description} </span> </MentionItem> ))} </MentionContent> </MentionPortal> </Mention> ); }; ``` # Menubar (/docs/components/menubar) ## Preview [#preview] <ComponentPreview name="menubar-demo" description="A visually persistent menu common in desktop applications."> ```tsx import { Menubar, MenubarMenu, MenubarTrigger, MenubarContent, MenubarItem, MenubarSeparator, MenubarCheckboxItem, MenubarRadioGroup, MenubarRadioItem, MenubarSubContent, MenubarSubTrigger, MenubarSub, MenubarShortcut, } from "@/components/ui/Menubar"; export function MenubarDemo() { return ( <Menubar> <MenubarMenu> <MenubarTrigger>File</MenubarTrigger> <MenubarContent className="w-20"> <MenubarItem> New Tab <MenubarShortcut>⌘T</MenubarShortcut> </MenubarItem> <MenubarItem> New Window <MenubarShortcut>⌘N</MenubarShortcut> </MenubarItem> <MenubarItem disabled>New Incognito Window</MenubarItem> <MenubarSeparator /> <MenubarSub> <MenubarSubTrigger>Share</MenubarSubTrigger> <MenubarSubContent className="w-20"> <MenubarItem>Email link</MenubarItem> <MenubarItem>Messages</MenubarItem> <MenubarItem>Notes</MenubarItem> </MenubarSubContent> </MenubarSub> <MenubarSeparator /> <MenubarItem> Print... <MenubarShortcut>⌘P</MenubarShortcut> </MenubarItem> </MenubarContent> </MenubarMenu> <MenubarMenu> <MenubarTrigger>Edit</MenubarTrigger> <MenubarContent className="w-20"> <MenubarItem> Undo <MenubarShortcut>⌘Z</MenubarShortcut> </MenubarItem> <MenubarItem> Redo <MenubarShortcut>⇧⌘Z</MenubarShortcut> </MenubarItem> <MenubarSeparator /> <MenubarSub> <MenubarSubTrigger>Find</MenubarSubTrigger> <MenubarSubContent className="w-20"> <MenubarItem>Search the web</MenubarItem> <MenubarSeparator /> <MenubarItem>Find...</MenubarItem> <MenubarItem>Find Next</MenubarItem> <MenubarItem>Find Previous</MenubarItem> </MenubarSubContent> </MenubarSub> <MenubarSeparator /> <MenubarItem>Cut</MenubarItem> <MenubarItem>Copy</MenubarItem> <MenubarItem>Paste</MenubarItem> </MenubarContent> </MenubarMenu> <MenubarMenu> <MenubarTrigger>View</MenubarTrigger> <MenubarContent className="w-20"> <MenubarCheckboxItem>Always Show Bookmarks Bar</MenubarCheckboxItem> <MenubarCheckboxItem checked>Always Show Full URLs</MenubarCheckboxItem> <MenubarSeparator /> <MenubarItem> Reload <MenubarShortcut>⌘R</MenubarShortcut> </MenubarItem> <MenubarItem disabled> Force Reload <MenubarShortcut>⇧⌘R</MenubarShortcut> </MenubarItem> <MenubarSeparator /> <MenubarItem>Toggle Fullscreen</MenubarItem> <MenubarSeparator /> <MenubarItem>Hide Sidebar</MenubarItem> </MenubarContent> </MenubarMenu> <MenubarMenu> <MenubarTrigger>Profiles</MenubarTrigger> <MenubarContent className="w-20"> <MenubarRadioGroup value="benoit"> <MenubarRadioItem value="andy">Andy</MenubarRadioItem> <MenubarRadioItem value="benoit">Benoit</MenubarRadioItem> <MenubarRadioItem value="Luis">Luis</MenubarRadioItem> </MenubarRadioGroup> <MenubarSeparator /> <MenubarItem>Edit...</MenubarItem> <MenubarSeparator /> <MenubarItem>Add Profile...</MenubarItem> </MenubarContent> </MenubarMenu> </Menubar> ) } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/menubar ``` ### Manual [#manual] <Steps> <Step> Install the following dependencies: ```bash pnpm install @radix-ui/react-icons radix-ui ``` </Step> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the Menubar component into your `components/ui/Menubar.tsx` file. ```tsx "use client"; /** * @description A visually persistent menu common in desktop applications. / import as React from "react"; import { Menubar as MenubarRadix } from "radix-ui"; import { CheckIcon, ChevronRightIcon, DotFilledIcon, } from "@radix-ui/react-icons"; import { cn } from "@/utils/class-names"; function Menubar({ className, ...props }: React.ComponentProps<typeof MenubarRadix.Root>) { return ( <MenubarRadix.Root data-slot="menubar" className={cn("flex", className)} {...props} /> ); } function MenubarMenu({ ...props }: React.ComponentProps<typeof MenubarRadix.Menu>) { return <MenubarRadix.Menu data-slot="menubar-menu" {...props} />; } function MenubarGroup({ ...props }: React.ComponentProps<typeof MenubarRadix.Group>) { return <MenubarRadix.Group data-slot="menubar-group" {...props} />; } function MenubarPortal({ ...props }: React.ComponentProps<typeof MenubarRadix.Portal>) { return <MenubarRadix.Portal data-slot="menubar-portal" {...props} />; } function MenubarRadioGroup({ ...props }: React.ComponentProps<typeof MenubarRadix.RadioGroup>) { return <MenubarRadix.RadioGroup data-slot="menubar-radio-group" {...props} />; } function MenubarTrigger({ className, ...props }: React.ComponentProps<typeof MenubarRadix.Trigger>) { return ( <MenubarRadix.Trigger data-slot="menubar-trigger" className={cn( "p-0.5 px-2 hover:bg-accent-3 flex relative cursor-pointer", className )} {...props} /> ); } function MenubarContent({ className, ...props }: React.ComponentProps<typeof MenubarRadix.Content>) { return ( <MenubarPortal> <MenubarRadix.Content data-slot="menubar-content" className={cn( "z-50 origin-(--radix-menubar-content-transform-origin) bg-gray-1 border border-gray-a6 rounded-sm relative shadow-md data-[state=open]:animate-popover-show data-[state=closed]:animate-popover-hide", className )} {...props} /> </MenubarPortal> ); } function MenubarItem({ className, ...props }: React.ComponentProps<typeof MenubarRadix.Item>) { return ( <MenubarRadix.Item data-slot="menubar-item" className={cn( "p-0.5 px-2 hover:bg-accent-3 flex relative cursor-pointer justify-between", className )} {...props} /> ); } function MenubarCheckboxItem({ children, className, ...props }: React.ComponentProps<typeof MenubarRadix.CheckboxItem>) { return ( <MenubarRadix.CheckboxItem data-slot="menubar-checkbox-item" className={cn( "p-0.5 px-2 hover:bg-accent-3 flex relative cursor-pointer", className )} {...props} > <span className="absolute left-0.5 top-0 bottom-0 items-center flex justify-center"> <MenubarRadix.ItemIndicator> <CheckIcon className="text-accent-9" /> </MenubarRadix.ItemIndicator> </span> {children} </MenubarRadix.CheckboxItem> ); } function MenubarRadioItem({ children, className, ...props }: React.ComponentProps<typeof MenubarRadix.RadioItem>) { return ( <MenubarRadix.RadioItem data-slot="menubar-radio-item" className={cn( "p-0.5 px-2 hover:bg-accent-3 flex relative cursor-pointer", className )} {...props} > <span className="absolute left-0.5 top-0 bottom-0 items-center flex justify-center"> <MenubarRadix.ItemIndicator> <DotFilledIcon className="fill-current text-accent-9" /> </MenubarRadix.ItemIndicator> </span> {children} </MenubarRadix.RadioItem> ); } function MenubarLabel({ className, ...props }: React.ComponentProps<typeof MenubarRadix.Label>) { return ( <MenubarRadix.Label data-slot="menubar-label" className={cn("p-0.5 px-2 text-gray-12", className)} {...props} /> ); } function MenubarSeparator({ className, ...props }: React.ComponentProps<typeof MenubarRadix.Separator>) { return ( <MenubarRadix.Separator data-slot="menubar-separator" className={cn("m-0.6 h-px bg-gray-a6", className)} {...props} /> ); } function MenubarShortcut({ ...props }: React.ComponentProps<"span">) { return <span data-slot="menubar-shortcut" {...props} />; } function MenubarSub({ ...props }: React.ComponentProps<typeof MenubarRadix.Sub>) { return <MenubarRadix.Sub data-slot="menubar-sub" {...props} />; } function MenubarSubTrigger({ children, className, ...props }: React.ComponentProps<typeof MenubarRadix.SubTrigger> & { inset?: boolean; }) { return ( <MenubarRadix.SubTrigger data-slot="menubar-sub-trigger" className={cn( "p-0.5 px-2 hover:bg-accent-3 flex relative cursor-pointer", className )} {...props} > {children} <div className="absolute right-0.5 top-0 bottom-0 items-center flex justify-center"> <ChevronRightIcon /> </div> </MenubarRadix.SubTrigger> ); } function MenubarSubContent({ className, ...props }: React.ComponentProps<typeof MenubarRadix.SubContent>) { return ( <MenubarRadix.SubContent data-slot="menubar-sub-content" className={cn( "z-50 origin-(--radix-menubar-content-transform-origin) bg-gray-1 border border-gray-a6 rounded-sm relative shadow-md data-[state=open]:animate-popover-show data-[state=closed]:animate-popover-hide", className )} {...props} /> ); } export { Menubar, MenubarPortal, MenubarMenu, MenubarTrigger, MenubarContent, MenubarGroup, MenubarSeparator, MenubarLabel, MenubarItem, MenubarShortcut, MenubarCheckboxItem, MenubarRadioGroup, MenubarRadioItem, MenubarSub, MenubarSubTrigger, MenubarSubContent, }; ``` </Step> </Steps> # Message Scroller (/docs/components/message-scroller) ## Preview [#preview] <ComponentPreview name="message-scroller-demo" description="A chat scroll container that anchors turns, follows streamed output, loads history without jumping, and jumps to any message."> ```tsx import * as React from "react"; import { Avatar, AvatarFallback, } from "@/components/ui/Avatar"; import { Bubble, BubbleContent } from "@/components/ui/Bubble"; import { Button } from "@/components/ui/Button"; import { Marker, MarkerContent, } from "@/components/ui/Marker"; import { Message, MessageAvatar, MessageContent, } from "@/components/ui/Message"; import { MessageScroller, MessageScrollerButton, MessageScrollerContent, MessageScrollerItem, MessageScrollerProvider, MessageScrollerViewport, useMessageScroller, } from "@/components/ui/MessageScroller"; export function MessageScrollerDemo() { const [messages, setMessages] = React.useState(seed); return ( <Transcript messages={messages} onSend={() => { const next = messages.length + 1; setMessages((prev) => [ ...prev, { id: String(next), role: "user", content: `Follow-up #${next}: keep my place while this streams.`, }, { id: String(next + 1), role: "assistant", content: "Anchored your turn near the top. New content can grow below without yanking the viewport unless you are following.", }, ]); }} /> ); } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/message-scroller ``` ### Manual [#manual] <Steps> <Step> Install the following dependencies: ```bash pnpm install @radix-ui/react-icons @shadcn/react ``` </Step> <Step> Copy and paste the button component into your `components/ui/Button.tsx` file. ```tsx /** * @description Displays a button or a component that looks like a button. / import as React from "react"; import { Slot } from "@radix-ui/react-slot"; import { cva, type VariantProps } from "class-variance-authority"; import { cn } from "@/utils/class-names"; const buttonVariants = cva("button", { variants: { variant: { default: "button-fill", fill: "button-fill", pill: "button-pill border border-gray-6 text-gray-11 bg-gray-2 hover:bg-gray-3", link: "button-link", menu: "button-menu", }, size: { default: "h-4", xs: "h-2.5", sm: "h-3", md: "h-4", lg: "h-5", xl: "h-6", icon: "w-3 h-3 p-0", "icon-md": "w-4 h-4 p-0", }, }, defaultVariants: { variant: "default", size: "default", }, }); interface ButtonProps extends React.ComponentProps<"button">, VariantProps<typeof buttonVariants> { asChild?: boolean; isDisabled?: boolean; isLoading?: boolean; isLoadingText?: string | React.ReactNode; mode?: VariantProps<typeof buttonVariants>["variant"]; label?: string | React.ReactNode; } const Button = React.forwardRef<HTMLButtonElement, ButtonProps>( (props: ButtonProps, ref) => { const { className, variant, mode, size, asChild = false, isDisabled, isLoading, isLoadingText, children, label, ...rest } = props; const Comp = asChild ? Slot : "button"; const disabled = isDisabled || isLoading || props.disabled; const effectiveVariant = variant ?? mode; return ( <Comp data-slot="button" className={cn( buttonVariants({ variant: effectiveVariant, size, className }), disabled && "opacity-50 cursor-not-allowed" )} ref={ref} disabled={disabled} {...rest} > {asChild ? ( children ) : ( <> {isLoading && isLoadingText ? isLoadingText : <>{label}{children}</>} </> )} </Comp> ); } ); Button.displayName = "Button"; export { Button, buttonVariants }; export type { ButtonProps }; export default Button; ``` </Step> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the MessageScroller component into your `components/ui/MessageScroller.tsx` file. ```tsx "use client"; /** * @description A chat scroll container that anchors turns, follows streamed output, and jumps to messages. / import as React from "react"; import { ArrowDownIcon } from "@radix-ui/react-icons"; import { MessageScroller as MessageScrollerPrimitive, useMessageScroller, useMessageScrollerScrollable, useMessageScrollerVisibility, } from "@shadcn/react/message-scroller"; import { cn } from "@/utils/class-names"; import { Button } from "@/components/ui/Button"; function MessageScrollerProvider( props: React.ComponentProps<typeof MessageScrollerPrimitive.Provider> ) { return <MessageScrollerPrimitive.Provider {...props} />; } function MessageScroller({ className, ...props }: React.ComponentProps<typeof MessageScrollerPrimitive.Root>) { return ( <MessageScrollerPrimitive.Root data-slot="message-scroller" className={cn( "group/message-scroller relative flex size-full min-h-0 flex-col overflow-hidden", className )} {...props} /> ); } function MessageScrollerViewport({ className, ...props }: React.ComponentProps<typeof MessageScrollerPrimitive.Viewport>) { return ( <MessageScrollerPrimitive.Viewport data-slot="message-scroller-viewport" className={cn( "size-full min-h-0 min-w-0 overflow-y-auto overscroll-contain contain-content data-pending-scroll:invisible", className )} {...props} /> ); } function MessageScrollerContent({ className, ...props }: React.ComponentProps<typeof MessageScrollerPrimitive.Content>) { return ( <MessageScrollerPrimitive.Content data-slot="message-scroller-content" className={cn("flex h-max min-h-full flex-col gap-2", className)} {...props} /> ); } function MessageScrollerItem({ className, scrollAnchor = false, ...props }: React.ComponentProps<typeof MessageScrollerPrimitive.Item>) { return ( <MessageScrollerPrimitive.Item data-slot="message-scroller-item" scrollAnchor={scrollAnchor} className={cn( "min-w-0 shrink-0 [contain-intrinsic-size:auto_10rem] [content-visibility:auto]", className )} {...props} /> ); } function MessageScrollerButton({ direction = "end", className, children, render, ...props }: React.ComponentProps<typeof MessageScrollerPrimitive.Button>) { return ( <MessageScrollerPrimitive.Button data-slot="message-scroller-button" data-direction={direction} direction={direction} className={cn( "absolute start-1/2 z-10 -translate-x-1/2 border border-gray-6 bg-gray-1 text-gray-12 transition-[translate,scale,opacity] duration-[250ms] motion-reduce:transition-none hover:bg-gray-3 hover:text-gray-12 data-[active=false]:pointer-events-none data-[active=false]:scale-95 data-[active=false]:opacity-0 data-[active=false]:duration-[250ms] data-[active=false]:ease-[cubic-bezier(0.7,0,0.84,0)] data-[active=true]:translate-y-0 data-[active=true]:scale-100 data-[active=true]:opacity-100 data-[active=true]:ease-[cubic-bezier(0.23,1,0.32,1)] data-[direction=end]:bottom-1.5 data-[direction=end]:data-[active=false]:translate-y-full data-[direction=start]:top-1.5 data-[direction=start]:data-[active=false]:-translate-y-full rtl:translate-x-1/2 data-[direction=start]:[&_svg]:rotate-180", className )} render={render ?? <Button variant="pill" size="icon" />} {...props} > {children ?? ( <> <ArrowDownIcon className="icon" /> <span className="sr-only"> {direction === "end" ? "Scroll to end" : "Scroll to start"} </span> </> )} </MessageScrollerPrimitive.Button> ); } export { MessageScrollerProvider, MessageScroller, MessageScrollerViewport, MessageScrollerContent, MessageScrollerItem, MessageScrollerButton, useMessageScroller, useMessageScrollerScrollable, useMessageScrollerVisibility, }; ``` </Step> </Steps> ## Usage [#usage] ### AnchoredTurns [#anchoredturns] ```tsx export const AnchoredTurns = () => { const messages: DemoMessage[] = [ { id: "a1", role: "user", content: "Anchor this user turn near the top.", }, { id: "a2", role: "assistant", content: "The reply streams under the anchored prompt so the exchange stays connected.", }, { id: "a3", role: "user", content: "Send another turn to see the next anchor settle.", }, { id: "a4", role: "assistant", content: "Each user row with scrollAnchor becomes the start of a turn.", }, ]; return ( <div className="flex h-[24rem] w-full max-w-lg flex-col overflow-hidden rounded-md border border-gray-6 bg-gray-1"> <MessageScrollerProvider defaultScrollPosition="last-anchor"> <MessageScroller className="flex-1"> <MessageScrollerViewport> <MessageScrollerContent className="gap-1 p-1"> {messages.map((message) => ( <MessageScrollerItem key={message.id} messageId={message.id} scrollAnchor={message.role === "user"} > <Message align={message.role === "user" ? "end" : "start"}> <MessageContent> <Bubble variant={ message.role === "user" ? "default" : "secondary" } align={message.role === "user" ? "end" : "start"} > <BubbleContent>{message.content}</BubbleContent> </Bubble> </MessageContent> </Message> </MessageScrollerItem> ))} </MessageScrollerContent> </MessageScrollerViewport> <MessageScrollerButton direction="start" /> <MessageScrollerButton direction="end" /> </MessageScroller> </MessageScrollerProvider> </div> ); }; ``` # Message (/docs/components/message) ## Preview [#preview] <ComponentPreview name="message-demo" description="Displays a message in a conversation, with optional avatar, header, footer, and alignment."> ```tsx import { Avatar, AvatarFallback, AvatarImage, } from "@/components/ui/Avatar"; import { Bubble, BubbleContent } from "@/components/ui/Bubble"; import { Button } from "@/components/ui/Button"; import { Marker, MarkerContent, MarkerIcon, } from "@/components/ui/Marker"; import { Message, MessageAvatar, MessageContent, MessageFooter, MessageGroup, MessageHeader, } from "@/components/ui/Message"; import { SymbolIcon } from "@radix-ui/react-icons"; export function MessageDemo() { return ( <div className="flex w-full max-w-lg flex-col gap-2"> <Message> <MessageAvatar> <Avatar> <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" /> <AvatarFallback>CN</AvatarFallback> </Avatar> </MessageAvatar> <MessageContent> <Bubble variant="secondary"> <BubbleContent>It's 4:55 PM. On a Friday.</BubbleContent> </Bubble> </MessageContent> </Message> <Message align="end"> <MessageContent> <Bubble> <BubbleContent>How can I help you today?</BubbleContent> </Bubble> <MessageFooter>Delivered</MessageFooter> </MessageContent> </Message> <Message> <Marker role="status"> <MarkerIcon> <SymbolIcon className="icon animate-spin" /> </MarkerIcon> <MarkerContent>Oliver is typing...</MarkerContent> </Marker> </Message> </div> ) } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/message ``` ### Manual [#manual] <Steps> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the Message component into your `components/ui/Message.tsx` file. ```tsx /** * @description Displays a message in a conversation, with optional avatar, header, footer, and alignment. / import as React from "react"; import { cn } from "@/utils/class-names"; function MessageGroup({ className, ...props }: React.ComponentProps<"div">) { return ( <div data-slot="message-group" className={cn("flex min-w-0 flex-col gap-1", className)} {...props} /> ); } function Message({ className, align = "start", ...props }: React.ComponentProps<"div"> & { align?: "start" | "end" }) { return ( <div data-slot="message" data-align={align} className={cn( "group/message relative flex w-full min-w-0 gap-0.5 text-sm data-[align=end]:flex-row-reverse", className )} {...props} /> ); } function MessageAvatar({ className, ...props }: React.ComponentProps<"div">) { return ( <div data-slot="message-avatar" className={cn( "flex w-fit min-w-3 shrink-0 items-center justify-center self-end overflow-hidden rounded-full bg-gray-3 group-has-data-[slot=message-footer]/message:-translate-y-2", className )} {...props} /> ); } function MessageContent({ className, ...props }: React.ComponentProps<"div">) { return ( <div data-slot="message-content" className={cn( "flex w-full min-w-0 flex-col gap-1 break-words group-data-[align=end]/message:*:data-slot:self-end", className )} {...props} /> ); } function MessageHeader({ className, ...props }: React.ComponentProps<"div">) { return ( <div data-slot="message-header" className={cn( "flex max-w-full min-w-0 items-center px-1 text-xs font-medium text-gray-11 group-has-data-[variant=ghost]/message:px-0", className )} {...props} /> ); } function MessageFooter({ className, ...props }: React.ComponentProps<"div">) { return ( <div data-slot="message-footer" className={cn( "flex max-w-full min-w-0 items-center px-1 text-xs font-medium text-gray-11 group-has-data-[variant=ghost]/message:px-0 group-data-[align=end]/message:justify-end", className )} {...props} /> ); } export { MessageGroup, Message, MessageAvatar, MessageContent, MessageFooter, MessageHeader, }; ``` </Step> </Steps> ## Usage [#usage] ### Alignment [#alignment] ```tsx export const Alignment = () => ( <div className="flex w-full max-w-lg flex-col gap-2"> <Message> <MessageAvatar> <Avatar> <AvatarFallback>AI</AvatarFallback> </Avatar> </MessageAvatar> <MessageContent> <Bubble variant="secondary"> <BubbleContent>The build failed during dependency installation.</BubbleContent> </Bubble> </MessageContent> </Message> <Message align="end"> <MessageContent> <Bubble> <BubbleContent>Can you share the exact error?</BubbleContent> </Bubble> </MessageContent> </Message> <Message> <MessageAvatar> <Avatar> <AvatarFallback>AI</AvatarFallback> </Avatar> </MessageAvatar> <MessageContent> <Bubble variant="secondary"> <BubbleContent> Something went wrong with the build. Try running it again. </BubbleContent> </Bubble> </MessageContent> </Message> </div> ) ``` ### Group [#group] ```tsx export const Group = () => ( <div className="flex w-full max-w-lg flex-col gap-2"> <MessageGroup> <Message> <MessageAvatar className="invisible" aria-hidden /> <MessageContent> <Bubble variant="secondary"> <BubbleContent>I checked the registry addresses.</BubbleContent> </Bubble> </MessageContent> </Message> <Message> <MessageAvatar> <Avatar> <AvatarFallback>AI</AvatarFallback> </Avatar> </MessageAvatar> <MessageContent> <Bubble variant="secondary"> <BubbleContent>They look correct on my end.</BubbleContent> </Bubble> </MessageContent> </Message> </MessageGroup> </div> ) ``` ### HeaderAndFooter [#headerandfooter] ```tsx export const HeaderAndFooter = () => ( <div className="flex w-full max-w-lg flex-col gap-2"> <Message> <MessageAvatar> <Avatar> <AvatarFallback>YO</AvatarFallback> </Avatar> </MessageAvatar> <MessageContent> <MessageHeader>You</MessageHeader> <Bubble variant="secondary"> <BubbleContent> Send the report to the team. Ping @shadcn if you need help. </BubbleContent> </Bubble> <MessageFooter>Just now</MessageFooter> </MessageContent> </Message> </div> ) ``` ### Actions [#actions] ```tsx export const Actions = () => ( <div className="flex w-full max-w-lg flex-col gap-2"> <Message> <MessageContent> <Bubble variant="ghost"> <BubbleContent> The install failure is coming from the workspace package. </BubbleContent> </Bubble> <MessageFooter className="gap-0.5"> <Button variant="pill" size="xs" type="button" aria-label="Copy"> Copy </Button> <Button variant="pill" size="xs" type="button" aria-label="Retry"> Retry </Button> </MessageFooter> </MessageContent> </Message> </div> ) ``` # Native Select (/docs/components/native-select) ## Preview [#preview] <ComponentPreview name="native-select-demo" description="A native select with the same field chrome as other inputs."> ```tsx import { NativeSelect, NativeSelectGroup, NativeSelectOption, } from "@/components/ui/NativeSelect"; export function NativeSelectDemo() { return ( <NativeSelect aria-label="Meal" defaultValue="breakfast"> <NativeSelectGroup label="Day"> <NativeSelectOption value="breakfast">Breakfast</NativeSelectOption> <NativeSelectOption value="lunch">Lunch</NativeSelectOption> <NativeSelectOption value="dinner">Dinner</NativeSelectOption> </NativeSelectGroup> </NativeSelect> ); } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/native-select ``` ### Manual [#manual] <Steps> <Step> Install the following dependencies: ```bash pnpm install @radix-ui/react-icons ``` </Step> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the NativeSelect component into your `components/ui/NativeSelect.tsx` file. ```tsx "use client"; /** * @description A native select. The closed control uses the same field chrome as other inputs. / import as React from "react"; import { ChevronDownIcon } from "@radix-ui/react-icons"; import { cn } from "@/utils/class-names"; function NativeSelect({ className, children, ...props }: React.ComponentProps<"select">) { return ( <div data-slot="native-select" className="relative w-full"> <select className={cn("w-full pe-4", className)} {...props}> {children} </select> <span className="pointer-events-none absolute inset-y-0 end-1 flex items-center"> <ChevronDownIcon className="icon" aria-hidden /> </span> </div> ); } function NativeSelectGroup(props: React.ComponentProps<"optgroup">) { return <optgroup data-slot="native-select-group" {...props} />; } function NativeSelectOption(props: React.ComponentProps<"option">) { return <option data-slot="native-select-option" {...props} />; } export { NativeSelect, NativeSelectGroup, NativeSelectOption }; ``` </Step> </Steps> # Navigation Bar (/docs/components/navigation-bar) ## Preview [#preview] <ComponentPreview name="navigation-bar-demo" description="Bottom navigation for phones."> ```tsx import { HomeIcon, PersonIcon, GearIcon } from "@radix-ui/react-icons"; import { NavigationBar, NavigationBarItem } from "@/components/ui/NavigationBar"; export function NavigationBarDemo() { return ( <div className="max-w-xl overflow-hidden rounded-sm border border-gray-6"> <NavigationBar> <NavigationBarItem active> <HomeIcon className="icon" /> <span>Home</span> </NavigationBarItem> <NavigationBarItem> <PersonIcon className="icon" /> <span>People</span> </NavigationBarItem> <NavigationBarItem> <GearIcon className="icon" /> <span>Settings</span> </NavigationBarItem> </NavigationBar> </div> ); } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/navigation-bar ``` ### Manual [#manual] <Steps> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the NavigationBar component into your `components/ui/NavigationBar.tsx` file. ```tsx "use client"; import * as React from "react"; import { cn } from "@/utils/class-names"; function NavigationBar({ className, label = "Primary", ...props }: React.ComponentProps<"nav"> & { label?: string }) { return ( <nav aria-label={label} data-slot="navigation-bar" className={cn( "flex items-stretch justify-around border-t border-gray-6 bg-gray-1", className, )} {...props} /> ); } function NavigationBarItem({ className, active, children, ...props }: React.ComponentProps<"button"> & { active?: boolean }) { return ( <button type="button" data-slot="navigation-bar-item" aria-current={active ? "page" : undefined} className={cn( "inline-flex min-w-0 flex-1 flex-col items-center gap-0.5 px-0.5 py-0.5 text-gray-11 hover:bg-gray-3 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent-8 aria-[current=page]:text-accent-11", className, )} {...props} > {children} </button> ); } export { NavigationBar, NavigationBarItem }; ``` </Step> </Steps> # Navigation Menu (/docs/components/navigation-menu) ## Preview [#preview] <ComponentPreview name="navigation-menu-demo" description="A collection of links for navigating websites."> ```tsx import React from "react"; import { ChevronDownIcon } from "@radix-ui/react-icons"; import { NavigationMenu, NavigationMenuList, NavigationMenuItem, NavigationMenuContent, NavigationMenuTrigger, NavigationMenuLink, NavigationMenuIndicator, NavigationMenuViewport, } from "@/components/ui/NavigationMenu"; export function NavigationMenuDemo() { return ( <NavigationMenu className="relative z-10 w-full justify-end flex"> <NavigationMenuList className="center m-0 flex p-1"> {/* Product Menu Item /} <NavigationMenuItem> <NavigationMenuTrigger> <li> <span> Product <ChevronDownIcon className="icon" /> </span> </li> </NavigationMenuTrigger> <NavigationMenuContent> <ul> <li> <NavigationMenuLink href="#">Overview</NavigationMenuLink> </li> <li> <NavigationMenuLink href="#">Features</NavigationMenuLink> </li> <li> <NavigationMenuLink href="#">Pricing</NavigationMenuLink> </li> </ul> </NavigationMenuContent> </NavigationMenuItem> {/ Solutions Menu Item /} <NavigationMenuItem> <NavigationMenuTrigger> <li> <span> Solutions <ChevronDownIcon className="icon" /> </span> </li> </NavigationMenuTrigger> <NavigationMenuContent> <ul> <li> <NavigationMenuLink href="#">Enterprise</NavigationMenuLink> </li> <li> <NavigationMenuLink href="#">Small Business</NavigationMenuLink> </li> </ul> </NavigationMenuContent> </NavigationMenuItem> {/ Company Menu Item (No Submenu) /} <NavigationMenuItem> <NavigationMenuLink href="#">Company</NavigationMenuLink> </NavigationMenuItem> {/ Blog Menu Item (No Submenu) */} <NavigationMenuItem> <NavigationMenuLink href="#">Blog</NavigationMenuLink> </NavigationMenuItem> </NavigationMenuList> </NavigationMenu> ); } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/navigation-menu ``` ### Manual [#manual] <Steps> <Step> Install the following dependencies: ```bash pnpm install radix-ui ``` </Step> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the NavigationMenu component into your `components/ui/NavigationMenu.tsx` file. ```tsx /** * @description A collection of links for navigating websites. / import as React from "react"; import { NavigationMenu as NavigationMenuRadix } from "radix-ui"; import { cn } from "@/utils/class-names"; function NavigationMenu({ className, children, ...props }: React.ComponentProps<typeof NavigationMenuRadix.Root>) { return ( <NavigationMenuRadix.Root data-slot="navigation-menu" className={cn(className)} {...props} > {children} </NavigationMenuRadix.Root> ); } function NavigationMenuList({ className, ...props }: React.ComponentProps<typeof NavigationMenuRadix.List>) { return ( <NavigationMenuRadix.List data-slot="navigation-menu-list" className={cn("flex", className)} {...props} /> ); } function NavigationMenuItem({ className, ...props }: React.ComponentProps<typeof NavigationMenuRadix.Item>) { return ( <NavigationMenuRadix.Item data-slot="navigation-menu-item" className={cn("relative", className)} {...props} /> ); } function NavigationMenuTrigger({ className, children, ...props }: React.ComponentProps<typeof NavigationMenuRadix.Trigger>) { return ( <NavigationMenuRadix.Trigger data-slot="navigation-menu-trigger" {...props} className={cn( "p-0.5 px-1 hover:bg-accent-3 flex relative cursor-pointer", className )} > {children} </NavigationMenuRadix.Trigger> ); } function NavigationMenuContent({ className, ...props }: React.ComponentProps<typeof NavigationMenuRadix.Content>) { return ( <NavigationMenuRadix.Content data-slot="navigation-menu-content" className={cn( "absolute top-full z-50 mt-0.5 origin-(--radix-navigation-menu-content-transform-origin) overflow-hidden rounded-md border border-gray-a6 bg-gray-1 shadow-md data-[state=open]:animate-popover-show data-[state=closed]:animate-popover-hide", className )} {...props} /> ); } function NavigationMenuViewport({ className, ...props }: React.ComponentProps<typeof NavigationMenuRadix.Viewport>) { return ( <NavigationMenuRadix.Viewport data-slot="navigation-menu-viewport" {...props} className={cn(className)} /> ); } function NavigationMenuLink({ className, ...props }: React.ComponentProps<typeof NavigationMenuRadix.Link>) { return ( <NavigationMenuRadix.Link data-slot="navigation-menu-link" className={cn( "p-0.5 px-1 hover:bg-accent-3 flex relative cursor-pointer items-center", className )} {...props} /> ); } function NavigationMenuIndicator({ className, ...props }: React.ComponentProps<typeof NavigationMenuRadix.Indicator>) { return ( <NavigationMenuRadix.Indicator data-slot="navigation-menu-indicator" className={cn(className)} {...props} > <div /> </NavigationMenuRadix.Indicator> ); } export { NavigationMenu, NavigationMenuList, NavigationMenuItem, NavigationMenuContent, NavigationMenuTrigger, NavigationMenuLink, NavigationMenuIndicator, NavigationMenuViewport, }; ``` </Step> </Steps> ## Usage [#usage] ### NavigationMenuDemo [#navigationmenudemo] ```tsx export function NavigationMenuDemo() { return ( <NavigationMenu> <NavigationMenuList className="flex-wrap"> <NavigationMenuItem> <NavigationMenuTrigger>Home</NavigationMenuTrigger> <NavigationMenuContent> <ul className="w-[400px]"> <ListItem href="/docs" title="Introduction"> Re-usable components built using Radix UI and Tailwind CSS. </ListItem> <ListItem href="/docs/installation" title="Installation"> How to install dependencies and structure your app. </ListItem> <ListItem href="/docs/primitives/typography" title="Typography"> Styles for headings, paragraphs, lists...etc </ListItem> </ul> </NavigationMenuContent> </NavigationMenuItem> <NavigationMenuItem> <NavigationMenuTrigger>Components</NavigationMenuTrigger> <NavigationMenuContent> <ul className="grid gap-0.5 w-[500px] grid-cols-2"> {components.map((component) => ( <ListItem key={component.title} title={component.title} href={component.href} > {component.description} </ListItem> ))} </ul> </NavigationMenuContent> </NavigationMenuItem> <NavigationMenuItem> <NavigationMenuLink>Docs</NavigationMenuLink> </NavigationMenuItem> <NavigationMenuItem> <NavigationMenuTrigger>List</NavigationMenuTrigger> <NavigationMenuContent> <ul className="grid gap-1 w-[400px]"> <li> <NavigationMenuLink> <div> <div className="font-medium">Components</div> <div>Browse all components in the library.</div> </div> </NavigationMenuLink> <NavigationMenuLink> <div> <div className="font-medium">Documentation</div> <div>Learn how to use the library.</div> </div> </NavigationMenuLink> <NavigationMenuLink> <div> <div>Blog</div> <div>Read our latest blog posts.</div> </div> </NavigationMenuLink> </li> </ul> </NavigationMenuContent> </NavigationMenuItem> <NavigationMenuItem className="block"> <NavigationMenuTrigger>Simple</NavigationMenuTrigger> <NavigationMenuContent> <ul className="grid gap-1"> <li> <NavigationMenuLink>Components</NavigationMenuLink> <NavigationMenuLink>Documentation</NavigationMenuLink> <NavigationMenuLink>Blocks</NavigationMenuLink> </li> </ul> </NavigationMenuContent> </NavigationMenuItem> <NavigationMenuItem className="block"> <NavigationMenuTrigger>With Icon</NavigationMenuTrigger> <NavigationMenuContent> <ul className="grid gap-1"> <li> <NavigationMenuLink>Backlog</NavigationMenuLink> <NavigationMenuLink>To Do</NavigationMenuLink> <NavigationMenuLink>Done</NavigationMenuLink> </li> </ul> </NavigationMenuContent> </NavigationMenuItem> </NavigationMenuList> </NavigationMenu> ); } ``` # Navigation Rail (/docs/components/navigation-rail) ## Preview [#preview] <ComponentPreview name="navigation-rail-demo" description="Side navigation for tablet and desktop, collapsed or expanded."> ```tsx import { HomeIcon, PersonIcon, GearIcon } from "@radix-ui/react-icons"; import { NavigationRail, NavigationRailItem, NavigationRailLabel, } from "@/components/ui/NavigationRail"; export function NavigationRailDemo() { return ( <div className="h-24 overflow-hidden rounded-sm border border-gray-6"> <NavigationRail> <NavigationRailItem active> <HomeIcon className="icon" /> <NavigationRailLabel>Home</NavigationRailLabel> </NavigationRailItem> <NavigationRailItem> <PersonIcon className="icon" /> <NavigationRailLabel>People</NavigationRailLabel> </NavigationRailItem> <NavigationRailItem> <GearIcon className="icon" /> <NavigationRailLabel>Settings</NavigationRailLabel> </NavigationRailItem> </NavigationRail> </div> ); } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/navigation-rail ``` ### Manual [#manual] <Steps> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the NavigationRail component into your `components/ui/NavigationRail.tsx` file. ```tsx "use client"; import * as React from "react"; import { cn } from "@/utils/class-names"; function NavigationRail({ className, expanded = false, label = "Primary", ...props }: React.ComponentProps<"nav"> & { expanded?: boolean; label?: string }) { return ( <nav aria-label={label} data-slot="navigation-rail" data-expanded={expanded ? "true" : "false"} className={cn( "group flex h-full flex-col gap-0.5 border-e border-gray-6 bg-gray-1 p-0.5", expanded ? "w-16" : "w-5", className, )} {...props} /> ); } function NavigationRailItem({ className, active, children, ...props }: React.ComponentProps<"button"> & { active?: boolean }) { return ( <button type="button" data-slot="navigation-rail-item" aria-current={active ? "page" : undefined} className={cn( "inline-flex items-center gap-0.5 rounded-sm px-1 py-0.5 text-gray-11 hover:bg-gray-3 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent-8 aria-[current=page]:bg-accent-3 aria-[current=page]:text-accent-11", className, )} {...props} > {children} </button> ); } function NavigationRailLabel({ className, ...props }: React.ComponentProps<"span">) { return ( <span data-slot="navigation-rail-label" className={cn("group-data-[expanded=false]:sr-only", className)} {...props} /> ); } export { NavigationRail, NavigationRailItem, NavigationRailLabel }; ``` </Step> </Steps> ## Usage [#usage] ### Expanded [#expanded] ```tsx export const Expanded = () => { return ( <div className="h-24 overflow-hidden rounded-sm border border-gray-6"> <NavigationRail expanded> <NavigationRailItem active> <HomeIcon className="icon" /> <NavigationRailLabel>Home</NavigationRailLabel> </NavigationRailItem> <NavigationRailItem> <PersonIcon className="icon" /> <NavigationRailLabel>People</NavigationRailLabel> </NavigationRailItem> <NavigationRailItem> <GearIcon className="icon" /> <NavigationRailLabel>Settings</NavigationRailLabel> </NavigationRailItem> </NavigationRail> </div> ); }; ``` # Pagination (/docs/components/pagination) ## Preview [#preview] <ComponentPreview name="pagination-demo" description="Pagination with page links, previous/next controls, and ellipsis."> ```tsx import { Pagination, PaginationContent, PaginationEllipsis, PaginationItem, PaginationLink, PaginationNext, PaginationPrevious, } from "@/components/ui/Pagination"; export function PaginationDemo() { return ( <Pagination> <PaginationContent> <PaginationItem> <PaginationPrevious href="#" /> </PaginationItem> <PaginationItem> <PaginationLink href="#">1</PaginationLink> </PaginationItem> <PaginationItem> <PaginationLink href="#" isActive> 2 </PaginationLink> </PaginationItem> <PaginationItem> <PaginationLink href="#">3</PaginationLink> </PaginationItem> <PaginationItem> <PaginationEllipsis /> </PaginationItem> <PaginationItem> <PaginationNext href="#" /> </PaginationItem> </PaginationContent> </Pagination> ) } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/pagination ``` ### Manual [#manual] <Steps> <Step> Install the following dependencies: ```bash pnpm install @radix-ui/react-icons ``` </Step> <Step> Copy and paste the button component into your `components/ui/Button.tsx` file. ```tsx /** * @description Displays a button or a component that looks like a button. / import as React from "react"; import { Slot } from "@radix-ui/react-slot"; import { cva, type VariantProps } from "class-variance-authority"; import { cn } from "@/utils/class-names"; const buttonVariants = cva("button", { variants: { variant: { default: "button-fill", fill: "button-fill", pill: "button-pill border border-gray-6 text-gray-11 bg-gray-2 hover:bg-gray-3", link: "button-link", menu: "button-menu", }, size: { default: "h-4", xs: "h-2.5", sm: "h-3", md: "h-4", lg: "h-5", xl: "h-6", icon: "w-3 h-3 p-0", "icon-md": "w-4 h-4 p-0", }, }, defaultVariants: { variant: "default", size: "default", }, }); interface ButtonProps extends React.ComponentProps<"button">, VariantProps<typeof buttonVariants> { asChild?: boolean; isDisabled?: boolean; isLoading?: boolean; isLoadingText?: string | React.ReactNode; mode?: VariantProps<typeof buttonVariants>["variant"]; label?: string | React.ReactNode; } const Button = React.forwardRef<HTMLButtonElement, ButtonProps>( (props: ButtonProps, ref) => { const { className, variant, mode, size, asChild = false, isDisabled, isLoading, isLoadingText, children, label, ...rest } = props; const Comp = asChild ? Slot : "button"; const disabled = isDisabled || isLoading || props.disabled; const effectiveVariant = variant ?? mode; return ( <Comp data-slot="button" className={cn( buttonVariants({ variant: effectiveVariant, size, className }), disabled && "opacity-50 cursor-not-allowed" )} ref={ref} disabled={disabled} {...rest} > {asChild ? ( children ) : ( <> {isLoading && isLoadingText ? isLoadingText : <>{label}{children}</>} </> )} </Comp> ); } ); Button.displayName = "Button"; export { Button, buttonVariants }; export type { ButtonProps }; export default Button; ``` </Step> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the Pagination component into your `components/ui/Pagination.tsx` file. ```tsx /** * @description Pagination with page links, previous/next controls, and ellipsis. / import as React from "react"; import { ChevronLeftIcon, ChevronRightIcon, DotsHorizontalIcon, } from "@radix-ui/react-icons"; import { cn } from "@/utils/class-names"; import { buttonVariants, type ButtonProps } from "@/components/ui/Button"; function Pagination({ className, ...props }: React.ComponentProps<"nav">) { return ( <nav role="navigation" aria-label="pagination" data-slot="pagination" className={cn("mx-auto flex w-full justify-center", className)} {...props} /> ); } function PaginationContent({ className, ...props }: React.ComponentProps<"ul">) { return ( <ul data-slot="pagination-content" className={cn("flex flex-row items-center gap-0.5", className)} {...props} /> ); } function PaginationItem({ className, ...props }: React.ComponentProps<"li">) { return ( <li data-slot="pagination-item" className={cn(className)} {...props} /> ); } type PaginationLinkProps = { isActive?: boolean; } & Pick<ButtonProps, "size"> & React.ComponentProps<"a">; function PaginationLink({ className, isActive, size = "icon", ...props }: PaginationLinkProps) { return ( <a aria-current={isActive ? "page" : undefined} data-slot="pagination-link" data-active={isActive} className={cn( buttonVariants({ variant: isActive ? "pill" : "link", size, }), "inline-flex items-center justify-center gap-0.5 no-underline", !isActive && "text-gray-11 hover:text-gray-12 hover:bg-gray-3", className )} {...props} /> ); } function PaginationPrevious({ className, text = "Previous", ...props }: React.ComponentProps<typeof PaginationLink> & { text?: string }) { return ( <PaginationLink aria-label="Go to previous page" size="default" className={cn("px-1", className)} {...props} > <ChevronLeftIcon className="icon cn-rtl-flip" /> {text ? <span className="hidden sm:inline">{text}</span> : null} </PaginationLink> ); } function PaginationNext({ className, text = "Next", ...props }: React.ComponentProps<typeof PaginationLink> & { text?: string }) { return ( <PaginationLink aria-label="Go to next page" size="default" className={cn("px-1", className)} {...props} > {text ? <span className="hidden sm:inline">{text}</span> : null} <ChevronRightIcon className="icon cn-rtl-flip" /> </PaginationLink> ); } function PaginationEllipsis({ className, ...props }: React.ComponentProps<"span">) { return ( <span aria-hidden data-slot="pagination-ellipsis" className={cn( "flex size-3 items-center justify-center text-gray-11", className )} {...props} > <DotsHorizontalIcon className="icon" /> <span className="sr-only">More pages</span> </span> ); } export { Pagination, PaginationContent, PaginationEllipsis, PaginationItem, PaginationLink, PaginationNext, PaginationPrevious, }; ``` </Step> </Steps> ## Usage [#usage] ### Simple [#simple] ```tsx export const Simple = () => ( <Pagination> <PaginationContent> <PaginationItem> <PaginationLink href="#">1</PaginationLink> </PaginationItem> <PaginationItem> <PaginationLink href="#" isActive> 2 </PaginationLink> </PaginationItem> <PaginationItem> <PaginationLink href="#">3</PaginationLink> </PaginationItem> <PaginationItem> <PaginationLink href="#">4</PaginationLink> </PaginationItem> <PaginationItem> <PaginationLink href="#">5</PaginationLink> </PaginationItem> </PaginationContent> </Pagination> ) ``` ### IconsOnly [#iconsonly] ```tsx export const IconsOnly = () => ( <Pagination> <PaginationContent> <PaginationItem> <PaginationPrevious href="#" text="" aria-label="Go to previous page" /> </PaginationItem> <PaginationItem> <PaginationNext href="#" text="" aria-label="Go to next page" /> </PaginationItem> </PaginationContent> </Pagination> ) ``` ### WithEllipsis [#withellipsis] ```tsx export const WithEllipsis = () => ( <Pagination> <PaginationContent> <PaginationItem> <PaginationPrevious href="#" /> </PaginationItem> <PaginationItem> <PaginationLink href="#">1</PaginationLink> </PaginationItem> <PaginationItem> <PaginationEllipsis /> </PaginationItem> <PaginationItem> <PaginationLink href="#">4</PaginationLink> </PaginationItem> <PaginationItem> <PaginationLink href="#" isActive> 5 </PaginationLink> </PaginationItem> <PaginationItem> <PaginationLink href="#">6</PaginationLink> </PaginationItem> <PaginationItem> <PaginationEllipsis /> </PaginationItem> <PaginationItem> <PaginationLink href="#">10</PaginationLink> </PaginationItem> <PaginationItem> <PaginationNext href="#" /> </PaginationItem> </PaginationContent> </Pagination> ) ``` # Phone Input (/docs/components/phone-input) ## Preview [#preview] <ComponentPreview name="phone-input-demo" description="A phone field with a calling code and a typed number."> ```tsx import { PhoneInput } from "@/components/ui/PhoneInput"; export function PhoneInputDemo() { return <PhoneInput placeholder="555 0100" />; } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/phone-input ``` ### Manual [#manual] <Steps> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the PhoneInput component into your `components/ui/PhoneInput.tsx` file. ```tsx "use client"; import * as React from "react"; import { cn } from "@/utils/class-names"; const callingCodes = [ { value: "1", label: "+1" }, { value: "34", label: "+34" }, { value: "44", label: "+44" }, { value: "52", label: "+52" }, { value: "81", label: "+81" }, ]; function PhoneInput({ className, code, defaultCode = "1", onCodeChange, label = "Phone", ...props }: Omit<React.ComponentProps<"input">, "type"> & { code?: string; defaultCode?: string; onCodeChange?: (code: string) => void; label?: string; }) { const [uncontrolledCode, setUncontrolledCode] = React.useState(defaultCode); const currentCode = code ?? uncontrolledCode; const id = React.useId(); return ( <div data-slot="phone-input" className={cn("flex w-full max-w-xl flex-col gap-0.5", className)}> <label htmlFor={id}>{label}</label> <div className="flex items-stretch gap-0.5"> <select aria-label="Calling code" value={currentCode} className="rounded-sm border border-gray-7 bg-gray-1 px-1 text-gray-12 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent-8" onChange={(event) => { if (code === undefined) setUncontrolledCode(event.target.value); onCodeChange?.(event.target.value); }} > {callingCodes.map((item) => ( <option key={item.value} value={item.value}> {item.label} </option> ))} </select> <input id={id} type="tel" inputMode="tel" autoComplete="tel-national" className="min-w-0 flex-1 rounded-sm border border-gray-7 bg-gray-1 px-1 py-0.5 text-gray-12 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent-8" {...props} /> </div> </div> ); } export { PhoneInput, callingCodes }; ``` </Step> </Steps> # Popover (/docs/components/popover) ## Preview [#preview] <ComponentPreview name="popover-demo" description="Displays rich content in a portal triggered by a button."> ```tsx import { useState } from "react"; import { Popover, PopoverTrigger, PopoverContent, PopoverClose, PopoverArrow, PopoverAnchor, } from "@/components/ui/Popover"; import { Button } from "@/components/ui/Button"; import { Input } from "@/components/ui/Input"; import { Label } from "@/components/ui/Label"; export function PopoverDemo() { return ( <Popover> <PopoverTrigger asChild> <Button variant="menu">Open Popover</Button> </PopoverTrigger> <PopoverContent className="w-30 p-1"> <div className="space-y-1"> <h4 className="font-medium leading-none">Dimensions</h4> <p className="text-sm text-gray-11"> Set the dimensions for the layer. </p> </div> </PopoverContent> </Popover> ) } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/popover ``` ### Manual [#manual] <Steps> <Step> Install the following dependencies: ```bash pnpm install @radix-ui/react-icons radix-ui ``` </Step> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the Popover component into your `components/ui/Popover.tsx` file. ```tsx "use client"; /** * @description Displays rich content in a portal triggered by a button. / import as React from "react"; import { Popover as PopoverRadix } from "radix-ui"; import { Cross2Icon } from "@radix-ui/react-icons"; import { cn } from "@/utils/class-names"; function Popover({ ...props }: React.ComponentProps<typeof PopoverRadix.Root>) { return <PopoverRadix.Root data-slot="popover" {...props} />; } function PopoverTrigger({ className, ...props }: React.ComponentProps<typeof PopoverRadix.Trigger>) { return ( <PopoverRadix.Trigger data-slot="popover-trigger" className={cn(className)} {...props} /> ); } function PopoverAnchor({ ...props }: React.ComponentProps<typeof PopoverRadix.Anchor>) { return <PopoverRadix.Anchor data-slot="popover-anchor" {...props} />; } function PopoverPortal({ ...props }: React.ComponentProps<typeof PopoverRadix.Portal>) { return <PopoverRadix.Portal data-slot="popover-portal" {...props} />; } function PopoverContent({ className, ...props }: React.ComponentProps<typeof PopoverRadix.Content>) { return ( <PopoverRadix.Portal> <PopoverRadix.Content data-slot="popover-content" collisionPadding={8} className={cn( className, "z-50 origin-(--radix-popover-content-transform-origin) bg-gray-1 border border-gray-a6 rounded-sm relative shadow-md data-[state=open]:animate-popover-show data-[state=closed]:animate-popover-hide" )} {...props} /> </PopoverRadix.Portal> ); } function PopoverArrow({ className, ...props }: React.ComponentProps<typeof PopoverRadix.Arrow>) { return ( <PopoverRadix.Arrow data-slot="popover-arrow" className={cn(className, "fill-gray-1")} {...props} /> ); } function PopoverClose({ className, ...props }: React.ComponentProps<typeof PopoverRadix.Close>) { return ( <PopoverRadix.Close data-slot="popover-close" className={cn( className, "absolute right-0.5 top-0.5 inline-flex items-center justify-center rounded-sm p-0.5 hover:bg-accent-3 cursor-pointer" )} {...props} > <Cross2Icon className="size-1" /> <span className="sr-only">Close</span> </PopoverRadix.Close> ); } export { Popover, PopoverTrigger, PopoverAnchor, PopoverPortal, PopoverContent, PopoverArrow, PopoverClose, }; ``` </Step> </Steps> ## Usage [#usage] ### WithCloseButton [#withclosebutton] ```tsx export const WithCloseButton = () => ( <Popover> <PopoverTrigger asChild> <Button variant="menu">Open Popover</Button> </PopoverTrigger> <PopoverContent className="w-30 p-1"> <PopoverClose /> <div className="space-y-1"> <h4 className="font-medium leading-none">Notifications</h4> <p className="text-sm text-gray-11"> You have 3 unread messages. Click the close button to dismiss. </p> </div> </PopoverContent> </Popover> ) ``` ### WithArrow [#witharrow] ```tsx export const WithArrow = () => ( <Popover> <PopoverTrigger asChild> <Button variant="menu">Open Popover</Button> </PopoverTrigger> <PopoverContent className="w-30 p-1"> <PopoverArrow /> <div className="space-y-1"> <h4 className="font-medium leading-none">Info</h4> <p className="text-sm text-gray-11"> This popover includes an arrow pointing to the trigger. </p> </div> </PopoverContent> </Popover> ) ``` ### Controlled [#controlled] ```tsx export const Controlled = () => { const [open, setOpen] = useState(false); return ( <div className="space-y-1"> <div className="flex items-center gap-0.5"> <span className="text-sm text-gray-11">Status:</span> <span className="text-sm font-medium">{open ? "Open" : "Closed"}</span> </div> <Popover open={open} onOpenChange={setOpen}> <PopoverTrigger asChild> <Button variant="menu">Toggle Popover</Button> </PopoverTrigger> <PopoverContent className="w-30 p-1"> <div className="space-y-1"> <h4 className="font-medium leading-none">Controlled Popover</h4> <p className="text-sm text-gray-11"> This popover's open state is controlled by React state. </p> <Button onClick={() => setOpen(false)} variant="link" className="w-full mt-0.5" > Close </Button> </div> </PopoverContent> </Popover> </div> ); }; ``` ### WithAnchor [#withanchor] ```tsx export const WithAnchor = () => ( <div className="space-y-1"> <p className="text-sm text-gray-11"> The popover can be anchored to a different element than the trigger. </p> <Popover> <PopoverAnchor asChild> <div className="inline-block p-1 bg-accent-3 rounded-sm"> Anchor Element </div> </PopoverAnchor> <PopoverTrigger asChild> <Button variant="menu" className="ml-1"> Open (Anchored) </Button> </PopoverTrigger> <PopoverContent className="w-30 p-1"> <div className="space-y-1"> <h4 className="font-medium leading-none">Anchored Popover</h4> <p className="text-sm text-gray-11"> This popover is positioned relative to the anchor element, not the trigger. </p> </div> </PopoverContent> </Popover> </div> ) ``` ### Positioning [#positioning] ```tsx export const Positioning = () => ( <div className="grid grid-cols-2 gap-1"> {(["top", "right", "bottom", "left"] as const).map((side) => ( <Popover key={side}> <PopoverTrigger asChild> <Button variant="menu" className="capitalize"> {side} </Button> </PopoverTrigger> <PopoverContent side={side} className="w-15 p-1"> <p className="text-sm"> Popover positioned on the <strong>{side}</strong> side. </p> </PopoverContent> </Popover> ))} </div> ) ``` # Presentation (/docs/components/presentation) ## Preview [#preview] <ComponentPreview name="presentation-demo" description="Composable PowerPoint viewer and editor built on @diceui/pptx."> ```tsx import * as React from "react"; import { Button } from "@/components/ui/Button"; import { Presentation, PresentationContent, PresentationError, PresentationLoading, PresentationSelection, PresentationSlide, PresentationThumbnailList, PresentationViewport, } from "@/components/ui/Presentation"; export function PresentationDemo() { const [file, setFile] = React.useState<ArrayBuffer | null>(null); const [error, setError] = React.useState<string | null>(null); const [picked, setPicked] = React.useState<File | null>(null); const inputRef = React.useRef<HTMLInputElement>(null); React.useEffect(() => { let cancelled = false; fetch(SAMPLE_PPTX) .then((response) => { if (!response.ok) { throw new Error("Failed to load sample pptx"); } return response.arrayBuffer(); }) .then((buffer) => { if (!cancelled) setFile(buffer); }) .catch((err: unknown) => { if (!cancelled) { setError(err instanceof Error ? err.message : "Failed to load sample"); } }); return () => { cancelled = true; }; }, []); const source = picked ?? file; return ( <div className="flex w-full flex-col gap-0.5"> <div className="flex flex-wrap items-center gap-0.5"> <input ref={inputRef} type="file" accept=".pptx,application/vnd.openxmlformats-officedocument.presentationml.presentation" className="sr-only" onChange={(event) => { const next = event.target.files?.[0] ?? null; setPicked(next); }} /> <Button type="button" variant="pill" size="sm" onClick={() => inputRef.current?.click()} > Open .pptx </Button> {error ? ( <span className="text-xs text-danger-contrast">{error}</span> ) : null} </div> <Presentation file={source ?? undefined} readOnly className="h-32 w-full overflow-hidden rounded-md border border-gray-6 bg-gray-1" > <PresentationThumbnailList /> <PresentationContent> <PresentationLoading /> <PresentationError /> <PresentationViewport> <PresentationSlide /> </PresentationViewport> </PresentationContent> </Presentation> </div> ); } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/presentation ``` ### Manual [#manual] <Steps> <Step> Install the following dependencies: ```bash pnpm install @diceui/pptx @radix-ui/react-icons ``` </Step> <Step> Copy and paste the button component into your `components/ui/Button.tsx` file. ```tsx /** * @description Displays a button or a component that looks like a button. / import as React from "react"; import { Slot } from "@radix-ui/react-slot"; import { cva, type VariantProps } from "class-variance-authority"; import { cn } from "@/utils/class-names"; const buttonVariants = cva("button", { variants: { variant: { default: "button-fill", fill: "button-fill", pill: "button-pill border border-gray-6 text-gray-11 bg-gray-2 hover:bg-gray-3", link: "button-link", menu: "button-menu", }, size: { default: "h-4", xs: "h-2.5", sm: "h-3", md: "h-4", lg: "h-5", xl: "h-6", icon: "w-3 h-3 p-0", "icon-md": "w-4 h-4 p-0", }, }, defaultVariants: { variant: "default", size: "default", }, }); interface ButtonProps extends React.ComponentProps<"button">, VariantProps<typeof buttonVariants> { asChild?: boolean; isDisabled?: boolean; isLoading?: boolean; isLoadingText?: string | React.ReactNode; mode?: VariantProps<typeof buttonVariants>["variant"]; label?: string | React.ReactNode; } const Button = React.forwardRef<HTMLButtonElement, ButtonProps>( (props: ButtonProps, ref) => { const { className, variant, mode, size, asChild = false, isDisabled, isLoading, isLoadingText, children, label, ...rest } = props; const Comp = asChild ? Slot : "button"; const disabled = isDisabled || isLoading || props.disabled; const effectiveVariant = variant ?? mode; return ( <Comp data-slot="button" className={cn( buttonVariants({ variant: effectiveVariant, size, className }), disabled && "opacity-50 cursor-not-allowed" )} ref={ref} disabled={disabled} {...rest} > {asChild ? ( children ) : ( <> {isLoading && isLoadingText ? isLoadingText : <>{label}{children}</>} </> )} </Comp> ); } ); Button.displayName = "Button"; export { Button, buttonVariants }; export type { ButtonProps }; export default Button; ``` </Step> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the use mobile hook into your `hooks/use-mobile.ts` file. ```ts import * as React from "react" const MOBILE_BREAKPOINT = 768 export function useIsMobile(breakpoint = MOBILE_BREAKPOINT) { const [isMobile, setIsMobile] = React.useState<boolean | undefined>(undefined) React.useEffect(() => { const mql = window.matchMedia(`(max-width: ${breakpoint - 1}px)`) const onChange = () => { setIsMobile(window.innerWidth < breakpoint) } mql.addEventListener("change", onChange) setIsMobile(window.innerWidth < breakpoint) return () => mql.removeEventListener("change", onChange) }, [breakpoint]) return !!isMobile } ``` </Step> <Step> Copy and paste the Presentation component into your `components/ui/Presentation.tsx` file. ```tsx "use client"; /** * @description Composable PowerPoint viewer and editor built on @diceui/pptx. / import as React from "react"; import { Presentation as PresentationPrimitive } from "@diceui/pptx"; import { ViewVerticalIcon } from "@radix-ui/react-icons"; import { cn } from "@/utils/class-names"; import { useIsMobile } from "@/hooks/use-mobile"; import { Button } from "@/components/ui/Button"; function PresentationProvider({ ...props }: PresentationPrimitive.Provider.Props) { return ( <PresentationPrimitive.Provider data-slot="presentation-provider" {...props} /> ); } function Presentation({ className, ...props }: PresentationPrimitive.Root.Props) { return ( <PresentationPrimitive.Root data-slot="presentation" className={cn("relative flex overflow-hidden", className)} {...props} /> ); } function PresentationContent({ className, ...props }: React.ComponentProps<"div">) { return ( <div data-slot="presentation-content" className={cn( "relative isolate flex flex-1 flex-col overflow-hidden", className )} {...props} /> ); } function PresentationViewport({ className, autoFit = true, autoFitPadding = 13, ...props }: PresentationPrimitive.Viewport.Props) { return ( <PresentationPrimitive.Viewport autoFit={autoFit} autoFitPadding={autoFitPadding} data-slot="presentation-viewport" className={cn( "flex flex-1 items-center justify-center overflow-hidden bg-gray-2", className )} {...props} /> ); } function PresentationSlide({ className, ...props }: PresentationPrimitive.Slide.Props) { return ( <PresentationPrimitive.Slide data-slot="presentation-slide" className={cn("border border-gray-6", className)} {...props} /> ); } function PresentationSelection({ className, ...props }: PresentationPrimitive.Selection.Props) { return ( <PresentationPrimitive.Selection data-slot="presentation-selection" className={cn("[--presentation-selection:var(--accent-8)]", className)} {...props} /> ); } function PresentationLoading({ className, children, ...props }: PresentationPrimitive.Loading.Props) { return ( <PresentationPrimitive.Loading data-slot="presentation-loading" className={cn( "absolute inset-0 z-10 flex items-center justify-center text-sm text-gray-11", className )} {...props} > {children ?? ((progress) => <span>Loading… {progress}%</span>)} </PresentationPrimitive.Loading> ); } function PresentationError({ className, children, ...props }: PresentationPrimitive.Error.Props) { return ( <PresentationPrimitive.Error data-slot="presentation-error" className={cn( "absolute inset-0 z-10 flex items-center justify-center text-sm text-danger-contrast", className )} {...props} > {children ?? ((error: Error) => <span>{error.message}</span>)} </PresentationPrimitive.Error> ); } function PresentationThumbnailItemPreview({ className, ...props }: PresentationPrimitive.ThumbnailItemPreview.Props) { return ( <PresentationPrimitive.ThumbnailItemPreview data-slot="presentation-thumbnail-item-preview" className={cn( "w-full overflow-hidden rounded-sm data-pending:animate-pulse data-pending:bg-gray-3", className )} {...props} /> ); } function PresentationThumbnailItemNumber({ className, ...props }: PresentationPrimitive.ThumbnailItemNumber.Props) { return ( <PresentationPrimitive.ThumbnailItemNumber data-slot="presentation-thumbnail-item-number" className={cn( "block shrink-0 text-center font-mono text-xs leading-none text-gray-11 tabular-nums", className )} {...props} /> ); } function PresentationThumbnailItem({ className, children, ...props }: PresentationPrimitive.ThumbnailItem.Props) { return ( <PresentationPrimitive.ThumbnailItem data-slot="presentation-thumbnail-item" className={cn( "relative flex w-full cursor-pointer gap-0.5 rounded-md border border-gray-6 p-0.5 outline-none hover:bg-gray-3", "ring-2 ring-transparent transition-[color,box-shadow] duration-100 focus-visible:ring-accent-8 data-active:bg-gray-3", className )} {...props} > {children ?? ( <> <PresentationThumbnailItemNumber /> <PresentationThumbnailItemPreview /> </> )} </PresentationPrimitive.ThumbnailItem> ); } function PresentationThumbnailList({ className, children, ...props }: PresentationPrimitive.ThumbnailList.Props) { const isMobile = useIsMobile(); const id = React.useId(); const [open, setOpen] = React.useState(false); const [wasMobile, setWasMobile] = React.useState(isMobile); const listRef = React.useRef<HTMLDivElement | null>(null); const triggerRef = React.useRef<HTMLButtonElement | null>(null); const isHidden = isMobile && !open; if (wasMobile !== isMobile) { setWasMobile(isMobile); setOpen(false); } React.useEffect(() => { if (!isMobile || !open) return; let pendingPointerId: number | null = null; function isInside(target: Node) { return ( !!listRef.current?.contains(target) || !!triggerRef.current?.contains(target) ); } function onPointerDown(event: PointerEvent) { pendingPointerId = isInside(event.target as Node) ? null : event.pointerId; } function onPointerUp(event: PointerEvent) { const isPendingPointer = pendingPointerId === event.pointerId; pendingPointerId = null; if (isPendingPointer && !isInside(event.target as Node)) setOpen(false); } function onPointerCancel() { pendingPointerId = null; } function onKeyDown(event: KeyboardEvent) { if (event.key === "Escape") setOpen(false); } document.addEventListener("pointerdown", onPointerDown); document.addEventListener("pointerup", onPointerUp); document.addEventListener("pointercancel", onPointerCancel); document.addEventListener("keydown", onKeyDown); return () => { document.removeEventListener("pointerdown", onPointerDown); document.removeEventListener("pointerup", onPointerUp); document.removeEventListener("pointercancel", onPointerCancel); document.removeEventListener("keydown", onKeyDown); }; }, [isMobile, open]); return ( <> {isMobile && ( <Button type="button" aria-controls={id} aria-expanded={open} aria-label="Toggle thumbnails" variant="pill" size="icon" ref={triggerRef} className="absolute top-0.5 left-0.5 z-10 bg-gray-1/80 backdrop-blur-sm" onClick={() => setOpen((value) => !value)} > <ViewVerticalIcon className="icon" aria-hidden /> </Button> )} <PresentationPrimitive.ThumbnailList id={id} aria-hidden={isHidden || undefined} data-slot="presentation-thumbnail-list" data-mobile={isMobile || undefined} inert={isHidden} ref={listRef} render={<aside />} className={cn( "flex w-12 shrink-0 flex-col gap-0.5 overflow-y-auto border-r border-gray-6 bg-gray-1 p-0.5", isMobile && "absolute inset-y-0 left-0 z-20 transition-transform", isHidden && "-translate-x-full", className )} {...props} > {children ?? (({ slides }) => slides.map((slide) => ( <PresentationThumbnailItem key={slide.id} slideId={slide.id} /> )))} </PresentationPrimitive.ThumbnailList> </> ); } export { Presentation, PresentationContent, PresentationError, PresentationLoading, PresentationProvider, PresentationSelection, PresentationSlide, PresentationThumbnailItem, PresentationThumbnailItemNumber, PresentationThumbnailItemPreview, PresentationThumbnailList, PresentationViewport, }; export { useCreatePresentationStore, useHistory, usePresentation, usePresentationStore, useSlide, useZoom, } from "@diceui/pptx"; ``` </Step> </Steps> ## Usage [#usage] ### Editing [#editing] ```tsx export const Editing = () => { const [file, setFile] = React.useState<ArrayBuffer | null>(null); const [error, setError] = React.useState<string | null>(null); const [picked, setPicked] = React.useState<File | null>(null); const inputRef = React.useRef<HTMLInputElement>(null); React.useEffect(() => { let cancelled = false; fetch(SAMPLE_PPTX) .then((response) => { if (!response.ok) { throw new Error("Failed to load sample pptx"); } return response.arrayBuffer(); }) .then((buffer) => { if (!cancelled) setFile(buffer); }) .catch((err: unknown) => { if (!cancelled) { setError(err instanceof Error ? err.message : "Failed to load sample"); } }); return () => { cancelled = true; }; }, []); const source = picked ?? file; return ( <div className="flex w-full flex-col gap-0.5"> <div className="flex flex-wrap items-center gap-0.5"> <input ref={inputRef} type="file" accept=".pptx,application/vnd.openxmlformats-officedocument.presentationml.presentation" className="sr-only" onChange={(event) => { const next = event.target.files?.[0] ?? null; setPicked(next); }} /> <Button type="button" variant="pill" size="sm" onClick={() => inputRef.current?.click()} > Open .pptx </Button> {error ? ( <span className="text-xs text-danger-contrast">{error}</span> ) : null} </div> <Presentation file={source ?? undefined} readOnly={false} className="h-32 w-full overflow-hidden rounded-md border border-gray-6 bg-gray-1" > <PresentationThumbnailList /> <PresentationContent> <PresentationLoading /> <PresentationError /> <PresentationViewport> <PresentationSlide> <PresentationSelection undoRedoShortcuts /> </PresentationSlide> </PresentationViewport> </PresentationContent> </Presentation> </div> ); }; ``` # Progress (/docs/components/progress) ## Preview [#preview] <ComponentPreview name="progress-demo" description="Displays an indicator showing the completion progress of a task."> ```tsx import { useEffect, useState } from "react"; import { Progress } from "@/components/ui/Progress"; export function ProgressDemo() { return ( <div className="w-[300px]"> <Progress value={60} /> </div> ) ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/progress ``` ### Manual [#manual] <Steps> <Step> Install the following dependencies: ```bash pnpm install radix-ui ``` </Step> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the Progress component into your `components/ui/Progress.tsx` file. ```tsx "use client"; /** * @description Displays an indicator showing the completion progress of a task. / import as React from "react"; import { Progress as ProgressRadix } from "radix-ui"; import { cn } from "@/utils/class-names"; function Progress({ className, value, ...props }: React.ComponentProps<typeof ProgressRadix.Root>) { return ( <ProgressRadix.Root data-slot="progress" className={cn( "relative h-0.5 w-full overflow-hidden rounded-full bg-gray-3", className )} {...props} > <ProgressRadix.Indicator data-slot="progress-indicator" className="bg-accent-9 h-full w-full flex-1 transition-all" style={{ transform: `translateX(-${100 - (value || 0)}%)` }} /> </ProgressRadix.Root> ); } export { Progress }; ``` </Step> </Steps> ## Usage [#usage] ### Zero [#zero] ```tsx export const Zero = () => ( <div className="w-[300px]"> <Progress value={0} /> </div> ) ``` ### Complete [#complete] ```tsx export const Complete = () => ( <div className="w-[300px]"> <Progress value={100} /> </div> ) ``` ### Simulated [#simulated] ```tsx export const Simulated = () => { const [progress, setProgress] = useState(13); useEffect(() => { const timer = setTimeout(() => setProgress(66), 500); return () => clearTimeout(timer); }, []); return ( <div className="w-[300px]"> <Progress value={progress} /> </div> ); }; ``` # Qr Code (/docs/components/qr-code) ## Preview [#preview] <ComponentPreview name="qr-code-demo" description="A square code for a short string, up to 17 bytes."> ```tsx import { QrCode } from "@/components/ui/QrCode"; export function QrCodeDemo() { return <QrCode value="AURA" label="Code for AURA" />; } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/qr-code ``` ### Manual [#manual] <Steps> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the QrCode component into your `components/ui/QrCode.tsx` file. ```tsx "use client"; import * as React from "react"; import { cn } from "@/utils/class-names"; const SIZE = 21; const DATA_CODEWORDS = 19; const ECC_CODEWORDS = 7; const MAX_BYTES = 17; function rsMultiply(x: number, y: number) { let z = 0; for (let i = 7; i >= 0; i--) { z = (z << 1) ^ ((z >>> 7) * 0x11d); z ^= ((y >>> i) & 1) * x; } return z & 0xff; } function rsDivisor(degree: number) { const result = new Array<number>(degree).fill(0); result[degree - 1] = 1; let root = 1; for (let i = 0; i < degree; i++) { for (let j = 0; j < result.length; j++) { result[j] = rsMultiply(result[j], root); if (j + 1 < result.length) result[j] ^= result[j + 1]; } root = rsMultiply(root, 0x02); } return result; } function rsRemainder(data: number[], divisor: number[]) { const result = new Array<number>(divisor.length).fill(0); for (const byte of data) { const factor = (byte ^ result[0]) & 0xff; result.copyWithin(0, 1); result[result.length - 1] = 0; for (let i = 0; i < result.length; i++) { result[i] ^= rsMultiply(divisor[i], factor); } } return result; } function pushBits(out: number[], value: number, length: number) { for (let i = length - 1; i >= 0; i--) out.push((value >>> i) & 1); } function dataCodewords(bytes: Uint8Array) { const bits: number[] = []; pushBits(bits, 0b0100, 4); pushBits(bits, bytes.length, 8); for (const byte of bytes) pushBits(bits, byte, 8); const capacity = DATA_CODEWORDS * 8; pushBits(bits, 0, Math.min(4, capacity - bits.length)); while (bits.length % 8 !== 0) bits.push(0); const data: number[] = []; for (let i = 0; i < bits.length; i += 8) { let value = 0; for (let j = 0; j < 8; j++) value = (value << 1) | bits[i + j]; data.push(value); } const pads = [0xec, 0x11]; let pad = 0; while (data.length < DATA_CODEWORDS) data.push(pads[pad++ % 2]); return data; } type Matrix = { modules: boolean[][]; fn: boolean[][] }; function createMatrix(): Matrix { return { modules: Array.from({ length: SIZE }, () => Array(SIZE).fill(false)), fn: Array.from({ length: SIZE }, () => Array(SIZE).fill(false)), }; } function setFunction(state: Matrix, x: number, y: number, dark: boolean) { state.modules[y][x] = dark; state.fn[y][x] = true; } function drawFinder(state: Matrix, cx: number, cy: number) { for (let dy = -4; dy <= 4; dy++) { for (let dx = -4; dx <= 4; dx++) { const xx = cx + dx; const yy = cy + dy; if (xx < 0 || yy < 0 || xx >= SIZE || yy >= SIZE) continue; const dist = Math.max(Math.abs(dx), Math.abs(dy)); setFunction(state, xx, yy, dist !== 2 && dist !== 4); } } } function drawFunctions(state: Matrix) { for (let i = 0; i < SIZE; i++) { setFunction(state, 6, i, i % 2 === 0); setFunction(state, i, 6, i % 2 === 0); } drawFinder(state, 3, 3); drawFinder(state, SIZE - 4, 3); drawFinder(state, 3, SIZE - 4); const reserved: Array<[number, number]> = []; for (let i = 0; i <= 5; i++) reserved.push([8, i]); reserved.push([8, 7], [8, 8], [7, 8]); for (let i = 9; i < 15; i++) reserved.push([14 - i, 8]); for (let i = 0; i < 8; i++) reserved.push([SIZE - 1 - i, 8]); for (let i = 8; i < 15; i++) reserved.push([8, SIZE - 15 + i]); reserved.push([8, SIZE - 8]); for (const [x, y] of reserved) state.fn[y][x] = true; state.modules[SIZE - 8][8] = true; } function placeData(state: Matrix, bits: number[]) { let index = 0; for (let right = SIZE - 1; right >= 1; right -= 2) { if (right === 6) right = 5; for (let vert = 0; vert < SIZE; vert++) { for (let j = 0; j < 2; j++) { const x = right - j; const upward = ((right + 1) & 2) === 0; const y = upward ? SIZE - 1 - vert : vert; if (!state.fn[y][x] && index < bits.length) { state.modules[y][x] = bits[index] === 1; index += 1; } } } } } function maskFlips(mask: number, x: number, y: number) { switch (mask) { case 0: return (x + y) % 2 === 0; case 1: return y % 2 === 0; case 2: return x % 3 === 0; case 3: return (x + y) % 3 === 0; case 4: return (Math.floor(x / 3) + Math.floor(y / 2)) % 2 === 0; case 5: return (x * y) % 2 + (x * y) % 3 === 0; case 6: return ((x * y) % 2 + (x * y) % 3) % 2 === 0; default: return ((x + y) % 2 + (x * y) % 3) % 2 === 0; } } function applyMask(state: Matrix, mask: number) { for (let y = 0; y < SIZE; y++) { for (let x = 0; x < SIZE; x++) { if (!state.fn[y][x] && maskFlips(mask, x, y)) state.modules[y][x] = !state.modules[y][x]; } } } function drawFormat(state: Matrix, mask: number) { const data = (1 << 3) | mask; let rem = data; for (let i = 0; i < 10; i++) rem = (rem << 1) ^ ((rem >>> 9) * 0x537); const bits = ((data << 10) | (rem & 0x3ff)) ^ 0x5412; const bit = (index: number) => ((bits >>> index) & 1) === 1; for (let i = 0; i <= 5; i++) setFunction(state, 8, i, bit(i)); setFunction(state, 8, 7, bit(6)); setFunction(state, 8, 8, bit(7)); setFunction(state, 7, 8, bit(8)); for (let i = 9; i < 15; i++) setFunction(state, 14 - i, 8, bit(i)); for (let i = 0; i < 8; i++) setFunction(state, SIZE - 1 - i, 8, bit(i)); for (let i = 8; i < 15; i++) setFunction(state, 8, SIZE - 15 + i, bit(i)); setFunction(state, 8, SIZE - 8, true); } function penalty(modules: boolean[][]) { let score = 0; const run = (read: (index: number) => boolean) => { let color = read(0); let length = 1; for (let i = 1; i < SIZE; i++) { if (read(i) === color) { length += 1; if (length === 5) score += 3; else if (length > 5) score += 1; } else { color = read(i); length = 1; } } }; for (let y = 0; y < SIZE; y++) run((x) => modules[y][x]); for (let x = 0; x < SIZE; x++) run((y) => modules[y][x]); for (let y = 0; y < SIZE - 1; y++) { for (let x = 0; x < SIZE - 1; x++) { const color = modules[y][x]; if (color === modules[y][x + 1] && color === modules[y + 1][x] && color === modules[y + 1][x + 1]) { score += 3; } } } let dark = 0; for (const row of modules) for (const cell of row) if (cell) dark += 1; const total = SIZE * SIZE; const balance = Math.ceil(Math.abs(dark * 20 - total * 10) / total) - 1; score += balance * 10; return score; } function encodeQrMatrix(value: string, forcedMask?: number) { const bytes = new TextEncoder().encode(value); if (bytes.length > MAX_BYTES) return null; const data = dataCodewords(bytes); const ecc = rsRemainder(data, rsDivisor(ECC_CODEWORDS)); const bits: number[] = []; for (const byte of [...data, ...ecc]) pushBits(bits, byte, 8); let best: boolean[][] | null = null; let bestScore = Number.POSITIVE_INFINITY; const masks = forcedMask === undefined ? [0, 1, 2, 3, 4, 5, 6, 7] : [forcedMask]; for (const mask of masks) { const state = createMatrix(); drawFunctions(state); placeData(state, bits); applyMask(state, mask); drawFormat(state, mask); const score = penalty(state.modules); if (score < bestScore) { bestScore = score; best = state.modules.map((row) => row.slice()); } } return best; } function QrCode({ className, value, label = "QR code", }: { className?: string; value: string; label?: string; }) { const modules = React.useMemo(() => encodeQrMatrix(value), [value]); if (!modules) { return ( <p data-slot="qr-code" className={cn("m-0 text-gray-11", className)}> This code holds {MAX_BYTES} bytes. </p> ); } const quiet = 4; return ( <svg data-slot="qr-code" role="img" aria-label={label} viewBox={`${-quiet} ${-quiet} ${SIZE + quiet * 2} ${SIZE + quiet * 2}`} className={cn("size-16", className)} > <rect x={-quiet} y={-quiet} width={SIZE + quiet * 2} height={SIZE + quiet * 2} className="fill-gray-1" /> {modules.flatMap((row, y) => row.map((on, x) => on ? <rect key={`${x}-${y}`} x={x} y={y} width="1" height="1" className="fill-gray-12" /> : null, ), )} </svg> ); } export { QrCode, encodeQrMatrix }; ``` </Step> </Steps> # Questionnaire (/docs/components/questionnaire) ## Preview [#preview] <ComponentPreview name="questionnaire-demo" description="One question at a time, built on Stepper."> ```tsx import { Input } from "@/components/ui/Input"; import { Questionnaire, Question, } from "@/components/ui/Questionnaire"; export function QuestionnaireDemo() { return ( <Questionnaire questions={[ { value: "name", title: "What should we call you?", description: "This name shows on the care plan.", content: <Input aria-label="Name" placeholder="Ada Lovelace" />, }, { value: "city", title: "Which city are you in?", content: <Input aria-label="City" placeholder="Lisbon" />, }, { value: "confirm", title: "Ready to save?", description: "You can go back and change an answer.", }, ]} /> ); } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/questionnaire ``` ### Manual [#manual] <Steps> <Step> Copy and paste the button component into your `components/ui/Button.tsx` file. ```tsx /** * @description Displays a button or a component that looks like a button. / import as React from "react"; import { Slot } from "@radix-ui/react-slot"; import { cva, type VariantProps } from "class-variance-authority"; import { cn } from "@/utils/class-names"; import { Spinner } from "@/components/ui/Spinner"; const buttonVariants = cva("button", { variants: { variant: { default: "button-fill", fill: "button-fill", pill: "button-pill border border-gray-6 text-gray-11 bg-gray-2 hover:bg-gray-3", link: "button-link", menu: "button-menu", }, size: { default: "h-4", xs: "h-2.5", sm: "h-3", md: "h-4", lg: "h-5", xl: "h-6", icon: "w-3 h-3 p-0", "icon-md": "w-4 h-4 p-0", }, }, defaultVariants: { variant: "default", size: "default", }, }); interface ButtonProps extends React.ComponentProps<"button">, VariantProps<typeof buttonVariants> { asChild?: boolean; isDisabled?: boolean; isLoading?: boolean; isLoadingText?: string | React.ReactNode; mode?: VariantProps<typeof buttonVariants>["variant"]; label?: string | React.ReactNode; } const Button = React.forwardRef<HTMLButtonElement, ButtonProps>( (props: ButtonProps, ref) => { const { className, variant, mode, size, asChild = false, isDisabled, isLoading, isLoadingText, children, label, ...rest } = props; const Comp = asChild ? Slot : "button"; const disabled = isDisabled || isLoading || props.disabled; const effectiveVariant = variant ?? mode; return ( <Comp data-slot="button" className={cn( buttonVariants({ variant: effectiveVariant, size, className }), disabled && "opacity-50 cursor-not-allowed" )} ref={ref} disabled={disabled} {...rest} > {asChild ? ( children ) : ( <> {isLoading && isLoadingText ? ( isLoadingText ) : ( <> {isLoading ? <Spinner /> : null} {label} {children} </> )} </> )} </Comp> ); } ); Button.displayName = "Button"; export { Button, buttonVariants }; export type { ButtonProps }; export default Button; ``` </Step> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the stepper component into your `components/ui/Stepper.tsx` file. ```tsx "use client"; import { useDirection } from "@radix-ui/react-direction"; import { Slot } from "@radix-ui/react-slot"; import { CheckIcon } from "@radix-ui/react-icons"; import * as React from "react"; import { useComposedRefs } from "@/utils/compose-refs"; import { cn } from "@/utils/class-names"; import { useAsRef } from "@/hooks/use-as-ref"; import { useIsomorphicLayoutEffect } from "@/hooks/use-isomorphic-layout-effect"; import { useLazyRef } from "@/hooks/use-lazy-ref"; const ROOT_NAME = "Stepper"; const LIST_NAME = "StepperList"; const ITEM_NAME = "StepperItem"; const TRIGGER_NAME = "StepperTrigger"; const INDICATOR_NAME = "StepperIndicator"; const SEPARATOR_NAME = "StepperSeparator"; const TITLE_NAME = "StepperTitle"; const DESCRIPTION_NAME = "StepperDescription"; const CONTENT_NAME = "StepperContent"; const PREV_NAME = "StepperPrev"; const NEXT_NAME = "StepperNext"; const ENTRY_FOCUS = "stepperFocusGroup.onEntryFocus"; const EVENT_OPTIONS = { bubbles: false, cancelable: true }; const ARROW_KEYS = ["ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight"]; type Direction = "ltr" | "rtl"; type Orientation = "horizontal" | "vertical"; type NavigationDirection = "next" | "prev"; type ActivationMode = "automatic" | "manual"; type DataState = "inactive" | "active" | "completed"; interface DivProps extends React.ComponentProps<"div"> { asChild?: boolean; } interface ButtonProps extends React.ComponentProps<"button"> { asChild?: boolean; } type ListElement = React.ComponentRef<typeof StepperList>; type TriggerElement = React.ComponentRef<typeof StepperTrigger>; function getId( id: string, variant: "trigger" | "content" | "title" | "description", value: string, ) { return `${id}-${variant}-${value}`; } type FocusIntent = "first" | "last" | "prev" | "next"; const MAP_KEY_TO_FOCUS_INTENT: Record<string, FocusIntent> = { ArrowLeft: "prev", ArrowUp: "prev", ArrowRight: "next", ArrowDown: "next", PageUp: "first", Home: "first", PageDown: "last", End: "last", }; function getDirectionAwareKey(key: string, dir?: Direction) { if (dir !== "rtl") return key; return key === "ArrowLeft" ? "ArrowRight" : key === "ArrowRight" ? "ArrowLeft" : key; } function getFocusIntent( event: React.KeyboardEvent<TriggerElement>, dir?: Direction, orientation?: Orientation, ) { const key = getDirectionAwareKey(event.key, dir); if (orientation === "horizontal" && ["ArrowUp", "ArrowDown"].includes(key)) return undefined; if (orientation === "vertical" && ["ArrowLeft", "ArrowRight"].includes(key)) return undefined; return MAP_KEY_TO_FOCUS_INTENT[key]; } function focusFirst( candidates: React.RefObject<TriggerElement | null>[], preventScroll = false, ) { const PREVIOUSLY_FOCUSED_ELEMENT = document.activeElement; for (const candidateRef of candidates) { const candidate = candidateRef.current; if (!candidate) continue; if (candidate === PREVIOUSLY_FOCUSED_ELEMENT) return; candidate.focus({ preventScroll }); if (document.activeElement !== PREVIOUSLY_FOCUSED_ELEMENT) return; } } function wrapArray<T>(array: T[], startIndex: number) { return array.map<T>( (_, index) => array[(startIndex + index) % array.length] as T, ); } function getDataState( value: string | undefined, itemValue: string, stepState: StepState | undefined, steps: Map<string, StepState>, variant: "item" | "separator" = "item", ): DataState { const stepKeys = Array.from(steps.keys()); const currentIndex = stepKeys.indexOf(itemValue); if (stepState?.completed) return "completed"; if (value === itemValue) { return variant === "separator" ? "inactive" : "active"; } if (value) { const activeIndex = stepKeys.indexOf(value); if (activeIndex > currentIndex) return "completed"; } return "inactive"; } interface StepState { value: string; completed: boolean; disabled: boolean; } interface StoreState { steps: Map<string, StepState>; value: string; } interface Store { subscribe: (callback: () => void) => () => void; getState: () => StoreState; setState: <K extends keyof StoreState>(key: K, value: StoreState[K]) => void; setStateWithValidation: ( value: string, direction: NavigationDirection, ) => Promise<boolean>; hasValidation: () => boolean; notify: () => void; addStep: (value: string, completed: boolean, disabled: boolean) => void; removeStep: (value: string) => void; setStep: (value: string, completed: boolean, disabled: boolean) => void; } const StoreContext = React.createContext<Store | null>(null); function useStoreContext(consumerName: string) { const context = React.useContext(StoreContext); if (!context) { throw new Error(`\`${consumerName}\` must be used within \`${ROOT_NAME}\``); } return context; } function useStore<T>(selector: (state: StoreState) => T): T { const store = useStoreContext("useStore"); const getSnapshot = React.useCallback( () => selector(store.getState()), [store, selector], ); return React.useSyncExternalStore(store.subscribe, getSnapshot, getSnapshot); } interface ItemData { id: string; ref: React.RefObject<TriggerElement | null>; value: string; active: boolean; disabled: boolean; } interface StepperContextValue { rootId: string; dir: Direction; orientation: Orientation; activationMode: ActivationMode; disabled: boolean; nonInteractive: boolean; loop: boolean; } const StepperContext = React.createContext<StepperContextValue | null>(null); function useStepperContext(consumerName: string) { const context = React.useContext(StepperContext); if (!context) { throw new Error(`\`${consumerName}\` must be used within \`${ROOT_NAME}\``); } return context; } interface StepperProps extends DivProps { value?: string; defaultValue?: string; onValueChange?: (value: string) => void; onValueComplete?: (value: string, completed: boolean) => void; onValueAdd?: (value: string) => void; onValueRemove?: (value: string) => void; onValidate?: ( value: string, direction: NavigationDirection, ) => boolean | Promise<boolean>; activationMode?: ActivationMode; dir?: Direction; orientation?: Orientation; disabled?: boolean; loop?: boolean; nonInteractive?: boolean; } function Stepper(props: StepperProps) { const { value, defaultValue, onValueChange, onValueComplete, onValueAdd, onValueRemove, onValidate, dir: dirProp, orientation = "horizontal", activationMode = "automatic", asChild, disabled = false, nonInteractive = false, loop = false, className, id, ...rootProps } = props; const listenersRef = useLazyRef(() => new Set<() => void>()); const stateRef = useLazyRef<StoreState>(() => ({ steps: new Map(), value: value ?? defaultValue ?? "", })); const propsRef = useAsRef({ onValueChange, onValueComplete, onValueAdd, onValueRemove, onValidate, }); const store = React.useMemo<Store>(() => { return { subscribe: (cb) => { listenersRef.current.add(cb); return () => listenersRef.current.delete(cb); }, getState: () => stateRef.current, setState: (key, value) => { if (Object.is(stateRef.current[key], value)) return; if (key === "value" && typeof value === "string") { stateRef.current.value = value; propsRef.current.onValueChange?.(value); } else { stateRef.current[key] = value; } store.notify(); }, setStateWithValidation: async (value, direction) => { if (!propsRef.current.onValidate) { store.setState("value", value); return true; } try { const isValid = await propsRef.current.onValidate(value, direction); if (isValid) { store.setState("value", value); } return isValid; } catch { return false; } }, hasValidation: () => !!propsRef.current.onValidate, addStep: (value, completed, disabled) => { const newStep: StepState = { value, completed, disabled }; stateRef.current.steps.set(value, newStep); propsRef.current.onValueAdd?.(value); store.notify(); }, removeStep: (value) => { stateRef.current.steps.delete(value); propsRef.current.onValueRemove?.(value); store.notify(); }, setStep: (value, completed, disabled) => { const step = stateRef.current.steps.get(value); if (step) { const updatedStep: StepState = { ...step, completed, disabled }; stateRef.current.steps.set(value, updatedStep); if (completed !== step.completed) { propsRef.current.onValueComplete?.(value, completed); } store.notify(); } }, notify: () => { for (const cb of listenersRef.current) { cb(); } }, }; }, [listenersRef, stateRef, propsRef]); useIsomorphicLayoutEffect(() => { if (value !== undefined) { store.setState("value", value); } }, [value]); const dir = useDirection(dirProp); const instanceId = React.useId(); const rootId = id ?? instanceId; const contextValue = React.useMemo<StepperContextValue>( () => ({ rootId, dir, orientation, activationMode, disabled, nonInteractive, loop, }), [rootId, dir, orientation, activationMode, disabled, nonInteractive, loop], ); const RootPrimitive = asChild ? Slot : "div"; return ( <StoreContext.Provider value={store}> <StepperContext.Provider value={contextValue}> <RootPrimitive id={rootId} data-disabled={disabled ? "" : undefined} data-orientation={orientation} data-slot="stepper" dir={dir} {...rootProps} className={cn( "flex gap-1.5", orientation === "horizontal" ? "w-full flex-col" : "flex-row", className, )} /> </StepperContext.Provider> </StoreContext.Provider> ); } interface FocusContextValue { tabStopId: string | null; onItemFocus: (tabStopId: string) => void; onItemShiftTab: () => void; onFocusableItemAdd: () => void; onFocusableItemRemove: () => void; onItemRegister: (item: ItemData) => void; onItemUnregister: (id: string) => void; getItems: () => ItemData[]; } const FocusContext = React.createContext<FocusContextValue | null>(null); function useFocusContext(consumerName: string) { const context = React.useContext(FocusContext); if (!context) { throw new Error( `\`${consumerName}\` must be used within \`FocusProvider\``, ); } return context; } interface StepperListProps extends DivProps { asChild?: boolean; } function StepperList(props: StepperListProps) { const { asChild, onBlur: onBlurProp, onFocus: onFocusProp, onMouseDown: onMouseDownProp, className, children, ref, ...listProps } = props; const context = useStepperContext(LIST_NAME); const orientation = context.orientation; const currentValue = useStore((state) => state.value); const propsRef = useAsRef({ onBlur: onBlurProp, onFocus: onFocusProp, onMouseDown: onMouseDownProp, }); const [tabStopId, setTabStopId] = React.useState<string | null>(null); const [isTabbingBackOut, setIsTabbingBackOut] = React.useState(false); const [focusableItemCount, setFocusableItemCount] = React.useState(0); const isClickFocusRef = React.useRef(false); const itemsRef = React.useRef<Map<string, ItemData>>(new Map()); const listRef = React.useRef<ListElement>(null); const composedRef = useComposedRefs(ref, listRef); const onItemFocus = React.useCallback((tabStopId: string) => { setTabStopId(tabStopId); }, []); const onItemShiftTab = React.useCallback(() => { setIsTabbingBackOut(true); }, []); const onFocusableItemAdd = React.useCallback(() => { setFocusableItemCount((prevCount) => prevCount + 1); }, []); const onFocusableItemRemove = React.useCallback(() => { setFocusableItemCount((prevCount) => prevCount - 1); }, []); const onItemRegister = React.useCallback((item: ItemData) => { itemsRef.current.set(item.id, item); }, []); const onItemUnregister = React.useCallback((id: string) => { itemsRef.current.delete(id); }, []); const getItems = React.useCallback(() => { return Array.from(itemsRef.current.values()) .filter((item) => item.ref.current) .sort((a, b) => { const elementA = a.ref.current; const elementB = b.ref.current; if (!elementA || !elementB) return 0; const position = elementA.compareDocumentPosition(elementB); if (position & Node.DOCUMENT_POSITION_FOLLOWING) { return -1; } if (position & Node.DOCUMENT_POSITION_PRECEDING) { return 1; } return 0; }); }, []); const onBlur = React.useCallback( (event: React.FocusEvent<ListElement>) => { propsRef.current.onBlur?.(event); if (event.defaultPrevented) return; setIsTabbingBackOut(false); }, [propsRef], ); const onFocus = React.useCallback( (event: React.FocusEvent<ListElement>) => { propsRef.current.onFocus?.(event); if (event.defaultPrevented) return; const isKeyboardFocus = !isClickFocusRef.current; if ( event.target === event.currentTarget && isKeyboardFocus && !isTabbingBackOut ) { const entryFocusEvent = new CustomEvent(ENTRY_FOCUS, EVENT_OPTIONS); event.currentTarget.dispatchEvent(entryFocusEvent); if (!entryFocusEvent.defaultPrevented) { const items = Array.from(itemsRef.current.values()).filter( (item) => !item.disabled, ); const selectedItem = currentValue ? items.find((item) => item.value === currentValue) : undefined; const activeItem = items.find((item) => item.active); const currentItem = items.find((item) => item.id === tabStopId); const candidateItems = [ selectedItem, activeItem, currentItem, ...items, ].filter(Boolean) as ItemData[]; const candidateRefs = candidateItems.map((item) => item.ref); focusFirst(candidateRefs, false); } } isClickFocusRef.current = false; }, [propsRef, isTabbingBackOut, currentValue, tabStopId], ); const onMouseDown = React.useCallback( (event: React.MouseEvent<ListElement>) => { propsRef.current.onMouseDown?.(event); if (event.defaultPrevented) return; isClickFocusRef.current = true; }, [propsRef], ); const focusContextValue = React.useMemo<FocusContextValue>( () => ({ tabStopId, onItemFocus, onItemShiftTab, onFocusableItemAdd, onFocusableItemRemove, onItemRegister, onItemUnregister, getItems, }), [ tabStopId, onItemFocus, onItemShiftTab, onFocusableItemAdd, onFocusableItemRemove, onItemRegister, onItemUnregister, getItems, ], ); const ListPrimitive = asChild ? Slot : "div"; return ( <FocusContext.Provider value={focusContextValue}> <ListPrimitive role="tablist" aria-orientation={orientation} data-orientation={orientation} data-slot="stepper-list" dir={context.dir} tabIndex={isTabbingBackOut || focusableItemCount === 0 ? -1 : 0} {...listProps} ref={composedRef} className={cn( "flex outline-none", orientation === "horizontal" ? "flex-row items-center" : "flex-col items-start", className, )} onBlur={onBlur} onFocus={onFocus} onMouseDown={onMouseDown} > {children} </ListPrimitive> </FocusContext.Provider> ); } interface StepperItemContextValue { value: string; stepState: StepState | undefined; } const StepperItemContext = React.createContext<StepperItemContextValue | null>( null, ); function useStepperItemContext(consumerName: string) { const context = React.useContext(StepperItemContext); if (!context) { throw new Error(`\`${consumerName}\` must be used within \`${ITEM_NAME}\``); } return context; } interface StepperItemProps extends DivProps { value: string; completed?: boolean; disabled?: boolean; } function StepperItem(props: StepperItemProps) { const { value: itemValue, completed = false, disabled = false, asChild, className, children, ref, ...itemProps } = props; const context = useStepperContext(ITEM_NAME); const store = useStoreContext(ITEM_NAME); const orientation = context.orientation; const value = useStore((state) => state.value); useIsomorphicLayoutEffect(() => { store.addStep(itemValue, completed, disabled); return () => { store.removeStep(itemValue); }; }, [itemValue, completed, disabled]); useIsomorphicLayoutEffect(() => { store.setStep(itemValue, completed, disabled); }, [itemValue, completed, disabled]); const stepState = useStore((state) => state.steps.get(itemValue)); const steps = useStore((state) => state.steps); const dataState = getDataState(value, itemValue, stepState, steps); const itemContextValue = React.useMemo<StepperItemContextValue>( () => ({ value: itemValue, stepState, }), [itemValue, stepState], ); const ItemPrimitive = asChild ? Slot : "div"; return ( <StepperItemContext.Provider value={itemContextValue}> <ItemPrimitive data-disabled={stepState?.disabled ? "" : undefined} data-orientation={orientation} data-state={dataState} data-slot="stepper-item" dir={context.dir} {...itemProps} ref={ref} className={cn( "relative flex not-last:flex-1 items-center", orientation === "horizontal" ? "flex-row" : "flex-col", className, )} > {children} </ItemPrimitive> </StepperItemContext.Provider> ); } function StepperTrigger(props: ButtonProps) { const { asChild, onClick: onClickProp, onFocus: onFocusProp, onKeyDown: onKeyDownProp, onMouseDown: onMouseDownProp, disabled, className, ref, ...triggerProps } = props; const context = useStepperContext(TRIGGER_NAME); const itemContext = useStepperItemContext(TRIGGER_NAME); const itemValue = itemContext.value; const store = useStoreContext(TRIGGER_NAME); const focusContext = useFocusContext(TRIGGER_NAME); const value = useStore((state) => state.value); const steps = useStore((state) => state.steps); const stepState = useStore((state) => state.steps.get(itemValue)); const propsRef = useAsRef({ onClick: onClickProp, onFocus: onFocusProp, onKeyDown: onKeyDownProp, onMouseDown: onMouseDownProp, }); const activationMode = context.activationMode; const orientation = context.orientation; const loop = context.loop; const stepIndex = Array.from(steps.keys()).indexOf(itemValue); const stepPosition = stepIndex + 1; const stepCount = steps.size; const triggerId = getId(context.rootId, "trigger", itemValue); const contentId = getId(context.rootId, "content", itemValue); const titleId = getId(context.rootId, "title", itemValue); const descriptionId = getId(context.rootId, "description", itemValue); const isDisabled = disabled || stepState?.disabled || context.disabled; const isActive = value === itemValue; const isTabStop = focusContext.tabStopId === triggerId; const dataState = getDataState(value, itemValue, stepState, steps); const triggerRef = React.useRef<TriggerElement>(null); const composedRef = useComposedRefs(ref, triggerRef); const isArrowKeyPressedRef = React.useRef(false); const isMouseClickRef = React.useRef(false); React.useEffect(() => { function onKeyDown(event: KeyboardEvent) { if (ARROW_KEYS.includes(event.key)) { isArrowKeyPressedRef.current = true; } } function onKeyUp() { isArrowKeyPressedRef.current = false; } document.addEventListener("keydown", onKeyDown); document.addEventListener("keyup", onKeyUp); return () => { document.removeEventListener("keydown", onKeyDown); document.removeEventListener("keyup", onKeyUp); }; }, []); useIsomorphicLayoutEffect(() => { focusContext.onItemRegister({ id: triggerId, ref: triggerRef, value: itemValue, active: isTabStop, disabled: !!isDisabled, }); if (!isDisabled) { focusContext.onFocusableItemAdd(); } return () => { focusContext.onItemUnregister(triggerId); if (!isDisabled) { focusContext.onFocusableItemRemove(); } }; }, [focusContext, triggerId, itemValue, isTabStop, isDisabled]); const onClick = React.useCallback( async (event: React.MouseEvent<TriggerElement>) => { propsRef.current.onClick?.(event); if (event.defaultPrevented) return; if (!isDisabled && !context.nonInteractive) { const currentStepIndex = Array.from(steps.keys()).indexOf(value ?? ""); const targetStepIndex = Array.from(steps.keys()).indexOf(itemValue); const direction = targetStepIndex > currentStepIndex ? "next" : "prev"; await store.setStateWithValidation(itemValue, direction); } }, [ isDisabled, context.nonInteractive, store, itemValue, value, steps, propsRef, ], ); const onFocus = React.useCallback( async (event: React.FocusEvent<TriggerElement>) => { propsRef.current.onFocus?.(event); if (event.defaultPrevented) return; focusContext.onItemFocus(triggerId); const isKeyboardFocus = !isMouseClickRef.current; if ( !isActive && !isDisabled && activationMode !== "manual" && !context.nonInteractive && isKeyboardFocus ) { const currentStepIndex = Array.from(steps.keys()).indexOf(value || ""); const targetStepIndex = Array.from(steps.keys()).indexOf(itemValue); const direction = targetStepIndex > currentStepIndex ? "next" : "prev"; await store.setStateWithValidation(itemValue, direction); } isMouseClickRef.current = false; }, [ focusContext, triggerId, activationMode, isActive, isDisabled, context.nonInteractive, store, itemValue, value, steps, propsRef, ], ); const onKeyDown = React.useCallback( async (event: React.KeyboardEvent<TriggerElement>) => { propsRef.current.onKeyDown?.(event); if (event.defaultPrevented) return; if (event.key === "Enter" && context.nonInteractive) { event.preventDefault(); return; } if ( (event.key === "Enter" || event.key === " ") && activationMode === "manual" && !context.nonInteractive ) { event.preventDefault(); if (!isDisabled && triggerRef.current) { triggerRef.current.click(); } return; } if (event.key === "Tab" && event.shiftKey) { focusContext.onItemShiftTab(); return; } if (event.target !== event.currentTarget) return; const focusIntent = getFocusIntent(event, context.dir, orientation); if (focusIntent !== undefined) { if (event.metaKey || event.ctrlKey || event.altKey || event.shiftKey) return; event.preventDefault(); const items = focusContext.getItems().filter((item) => !item.disabled); let candidateRefs = items.map((item) => item.ref); if (focusIntent === "last") { candidateRefs.reverse(); } else if (focusIntent === "prev" || focusIntent === "next") { if (focusIntent === "prev") candidateRefs.reverse(); const currentIndex = candidateRefs.findIndex( (ref) => ref.current === event.currentTarget, ); candidateRefs = loop ? wrapArray(candidateRefs, currentIndex + 1) : candidateRefs.slice(currentIndex + 1); } if (store.hasValidation() && candidateRefs.length > 0) { const nextRef = candidateRefs[0]; const nextElement = nextRef?.current; const nextItem = items.find( (item) => item.ref.current === nextElement, ); if (nextItem && nextItem.value !== itemValue) { const currentStepIndex = Array.from(steps.keys()).indexOf( value || "", ); const targetStepIndex = Array.from(steps.keys()).indexOf( nextItem.value, ); const direction: NavigationDirection = targetStepIndex > currentStepIndex ? "next" : "prev"; if (direction === "next") { const isValid = await store.setStateWithValidation( nextItem.value, direction, ); if (!isValid) return; } else { store.setState("value", nextItem.value); } queueMicrotask(() => nextElement?.focus()); return; } } queueMicrotask(() => focusFirst(candidateRefs)); } }, [ focusContext, context.nonInteractive, context.dir, activationMode, orientation, loop, isDisabled, store, propsRef, itemValue, value, steps, ], ); const onMouseDown = React.useCallback( (event: React.MouseEvent<TriggerElement>) => { propsRef.current.onMouseDown?.(event); if (event.defaultPrevented) return; isMouseClickRef.current = true; if (isDisabled) { event.preventDefault(); } else { focusContext.onItemFocus(triggerId); } }, [focusContext, triggerId, isDisabled, propsRef], ); const TriggerPrimitive = asChild ? Slot : "button"; return ( <TriggerPrimitive id={triggerId} role="tab" type="button" aria-controls={contentId} aria-current={isActive ? "step" : undefined} aria-describedby={`${titleId} ${descriptionId}`} aria-posinset={stepPosition} aria-selected={isActive} aria-setsize={stepCount} data-disabled={isDisabled ? "" : undefined} data-state={dataState} data-slot="stepper-trigger" disabled={isDisabled} tabIndex={isTabStop ? 0 : -1} {...triggerProps} ref={composedRef} className={cn( "inline-flex items-center justify-center gap-1 rounded-md text-left outline-none transition-all cursor-pointer", "focus-visible:border-accent-8 focus-visible:ring-[3px] focus-visible:ring-accent-a8", "disabled:pointer-events-none disabled:opacity-50 disabled:cursor-not-allowed", "aria-invalid:border-danger aria-invalid:ring-danger/20", "[&_svg:not([class*='size-'])]:size-2 [&_svg]:pointer-events-none [&_svg]:shrink-0", "not-has-data-[slot=description]:rounded-full not-has-data-[slot=title]:rounded-full", className, )} onClick={onClick} onFocus={onFocus} onKeyDown={onKeyDown} onMouseDown={onMouseDown} /> ); } interface StepperIndicatorProps extends Omit<DivProps, "children"> { children?: React.ReactNode | ((dataState: DataState) => React.ReactNode); } function StepperIndicator(props: StepperIndicatorProps) { const { className, children, asChild, ref, ...indicatorProps } = props; const context = useStepperContext(INDICATOR_NAME); const itemContext = useStepperItemContext(INDICATOR_NAME); const value = useStore((state) => state.value); const itemValue = itemContext.value; const stepState = useStore((state) => state.steps.get(itemValue)); const steps = useStore((state) => state.steps); const stepPosition = Array.from(steps.keys()).indexOf(itemValue) + 1; const dataState = getDataState(value, itemValue, stepState, steps); const IndicatorPrimitive = asChild ? Slot : "div"; return ( <IndicatorPrimitive data-state={dataState} data-slot="stepper-indicator" dir={context.dir} {...indicatorProps} ref={ref} className={cn( "flex size-3 shrink-0 items-center justify-center rounded-full border-2 font-medium transition-colors", "border-gray-7 bg-gray-2 text-gray-11", "data-[state=active]:border-accent-8 data-[state=active]:bg-accent-9 data-[state=active]:text-accent-contrast", "data-[state=completed]:border-accent-8 data-[state=completed]:bg-accent-9 data-[state=completed]:text-accent-contrast", className, )} > {typeof children === "function" ? ( children(dataState) ) : children ? ( children ) : dataState === "completed" ? ( <CheckIcon className="icon" /> ) : ( stepPosition )} </IndicatorPrimitive> ); } interface StepperSeparatorProps extends DivProps { forceMount?: boolean; } function StepperSeparator(props: StepperSeparatorProps) { const { className, asChild, forceMount = false, ref, ...separatorProps } = props; const context = useStepperContext(SEPARATOR_NAME); const itemContext = useStepperItemContext(SEPARATOR_NAME); const value = useStore((state) => state.value); const steps = useStore((state) => state.steps); const orientation = context.orientation; const stepIndex = Array.from(steps.keys()).indexOf(itemContext.value); const isLastStep = stepIndex === steps.size - 1; if (isLastStep && !forceMount) return null; const dataState = getDataState( value, itemContext.value, itemContext.stepState, steps, "separator", ); const SeparatorPrimitive = asChild ? Slot : "div"; return ( <SeparatorPrimitive role="separator" aria-hidden="true" aria-orientation={orientation} data-orientation={orientation} data-state={dataState} data-slot="stepper-separator" dir={context.dir} {...separatorProps} ref={ref} className={cn( "bg-gray-6 transition-colors mx-1", "data-[state=active]:bg-accent-8 data-[state=completed]:bg-accent-8", orientation === "horizontal" ? "h-px flex-1" : "h-10 w-px", className, )} /> ); } interface StepperTitleProps extends React.ComponentProps<"span"> { asChild?: boolean; } function StepperTitle(props: StepperTitleProps) { const { className, asChild, ref, ...titleProps } = props; const context = useStepperContext(TITLE_NAME); const itemContext = useStepperItemContext(TITLE_NAME); const titleId = getId(context.rootId, "title", itemContext.value); const TitlePrimitive = asChild ? Slot : "span"; return ( <TitlePrimitive id={titleId} data-slot="title" dir={context.dir} {...titleProps} ref={ref} className={cn("font-medium text-gray-12", className)} /> ); } interface StepperDescriptionProps extends React.ComponentProps<"span"> { asChild?: boolean; } function StepperDescription(props: StepperDescriptionProps) { const { className, asChild, ref, ...descriptionProps } = props; const context = useStepperContext(DESCRIPTION_NAME); const itemContext = useStepperItemContext(DESCRIPTION_NAME); const descriptionId = getId(context.rootId, "description", itemContext.value); const DescriptionPrimitive = asChild ? Slot : "span"; return ( <DescriptionPrimitive id={descriptionId} data-slot="description" dir={context.dir} {...descriptionProps} ref={ref} className={cn("text-gray-11", className)} /> ); } interface StepperContentProps extends DivProps { value: string; forceMount?: boolean; } function StepperContent(props: StepperContentProps) { const { value: valueProp, asChild, forceMount = false, ref, className, ...contentProps } = props; const context = useStepperContext(CONTENT_NAME); const value = useStore((state) => state.value); const contentId = getId(context.rootId, "content", valueProp); const triggerId = getId(context.rootId, "trigger", valueProp); if (valueProp !== value && !forceMount) return null; const ContentPrimitive = asChild ? Slot : "div"; return ( <ContentPrimitive id={contentId} role="tabpanel" aria-labelledby={triggerId} data-slot="stepper-content" dir={context.dir} {...contentProps} ref={ref} className={cn("flex-1 outline-none", className)} /> ); } function StepperPrev(props: ButtonProps) { const { asChild, onClick: onClickProp, disabled, ...prevProps } = props; const store = useStoreContext(PREV_NAME); const value = useStore((state) => state.value); const steps = useStore((state) => state.steps); const propsRef = useAsRef({ onClick: onClickProp, }); const stepKeys = Array.from(steps.keys()); const currentIndex = value ? stepKeys.indexOf(value) : -1; const isDisabled = disabled || currentIndex <= 0; const onClick = React.useCallback( async (event: React.MouseEvent<HTMLButtonElement>) => { propsRef.current.onClick?.(event); if (event.defaultPrevented || isDisabled) return; const prevIndex = Math.max(currentIndex - 1, 0); const prevStepValue = stepKeys[prevIndex]; if (prevStepValue) { store.setState("value", prevStepValue); } }, [propsRef, isDisabled, currentIndex, stepKeys, store], ); const PrevPrimitive = asChild ? Slot : "button"; return ( <PrevPrimitive type="button" data-slot="stepper-prev" disabled={isDisabled} {...prevProps} onClick={onClick} /> ); } function StepperNext(props: ButtonProps) { const { asChild, onClick: onClickProp, disabled, ...nextProps } = props; const store = useStoreContext(NEXT_NAME); const value = useStore((state) => state.value); const steps = useStore((state) => state.steps); const propsRef = useAsRef({ onClick: onClickProp, }); const stepKeys = Array.from(steps.keys()); const currentIndex = value ? stepKeys.indexOf(value) : -1; const isDisabled = disabled || currentIndex >= stepKeys.length - 1; const onClick = React.useCallback( async (event: React.MouseEvent<HTMLButtonElement>) => { propsRef.current.onClick?.(event); if (event.defaultPrevented || isDisabled) return; const nextIndex = Math.min(currentIndex + 1, stepKeys.length - 1); const nextStepValue = stepKeys[nextIndex]; if (nextStepValue) { await store.setStateWithValidation(nextStepValue, "next"); } }, [propsRef, isDisabled, currentIndex, stepKeys, store], ); const NextPrimitive = asChild ? Slot : "button"; return ( <NextPrimitive type="button" data-slot="stepper-next" disabled={isDisabled} {...nextProps} onClick={onClick} /> ); } export { Stepper, StepperList, StepperItem, StepperTrigger, StepperIndicator, StepperSeparator, StepperTitle, StepperDescription, StepperContent, StepperPrev, StepperNext, useStore as useStepper, type StepperProps, }; ``` </Step> <Step> Copy and paste the Questionnaire component into your `components/ui/Questionnaire.tsx` file. ```tsx "use client"; /** * @description One question at a time, built on Stepper. / import as React from "react"; import { Button } from "@/components/ui/Button"; import { Stepper, StepperContent, StepperIndicator, StepperItem, StepperList, StepperNext, StepperPrev, StepperSeparator, StepperTitle, StepperTrigger, } from "@/components/ui/Stepper"; import { cn } from "@/utils/class-names"; function Question({ title, description, step, total, children, className, }: { title: string; description?: string; step?: number; total?: number; children?: React.ReactNode; className?: string; }) { const titleId = React.useId(); return ( <section aria-labelledby={titleId} data-slot="single-question" className={cn("grid gap-1", className)} > {step && total ? ( <p className="text-sm text-gray-11"> Question {step} of {total} </p> ) : null} <h2 id={titleId}>{title}</h2> {description ? <p className="text-gray-11">{description}</p> : null} <div className="grid gap-1">{children}</div> </section> ); } type QuestionnaireQuestion = { value: string; title: string; description?: string; content?: React.ReactNode; }; function Questionnaire({ questions, className, }: { questions: QuestionnaireQuestion[]; className?: string; }) { return ( <Stepper defaultValue={questions[0]?.value} className={cn("grid w-full gap-2", className)} > <StepperList> {questions.map((question, index) => ( <StepperItem key={question.value} value={question.value}> <StepperTrigger> <StepperIndicator /> <StepperTitle>{question.title}</StepperTitle> </StepperTrigger> {index < questions.length - 1 ? <StepperSeparator /> : null} </StepperItem> ))} </StepperList> {questions.map((question, index) => ( <StepperContent key={question.value} value={question.value} className="grid gap-1" > <Question title={question.title} description={question.description} step={index + 1} total={questions.length} > {question.content} </Question> <div className="flex items-center gap-1"> <StepperPrev asChild> <Button type="button" variant="pill"> Back </Button> </StepperPrev> <StepperNext asChild> <Button type="button"> {index === questions.length - 1 ? "Finish" : "Continue"} </Button> </StepperNext> </div> </StepperContent> ))} </Stepper> ); } export { Questionnaire, Question }; export type { QuestionnaireQuestion }; ``` </Step> </Steps> ## Usage [#usage] ### Shell [#shell] ```tsx export const Shell = () => { return ( <Question title="How are you sleeping?" description="Pick the answer that fits this week." step={1} total={3} > <Input aria-label="Sleep" placeholder="About 7 hours" /> </Question> ); }; ``` # Radio Group (/docs/components/radio-group) ## Preview [#preview] <ComponentPreview name="radio-group-demo" description="Re-usable components built using Radix UI and Tailwind CSS."> ```tsx import { useState } from "react"; import { RadioGroup, RadioGroupItem, } from "@/components/ui/RadioGroup"; export function RadioGroupDemo() { const [value, setValue] = useState("option-1"); return ( <RadioGroup value={value} onValueChange={setValue} className="flex flex-col gap-0.5" > <div className="flex items-center gap-1"> <RadioGroupItem value="option-1" id="option-1" /> <label htmlFor="option-1" className="text-sm font-medium leading-none cursor-pointer" > Option 1 </label> </div> <div className="flex items-center gap-1"> <RadioGroupItem value="option-2" id="option-2" /> <label htmlFor="option-2" className="text-sm font-medium leading-none cursor-pointer" > Option 2 </label> </div> <div className="flex items-center gap-1"> <RadioGroupItem value="option-3" id="option-3" /> <label htmlFor="option-3" className="text-sm font-medium leading-none cursor-pointer" > Option 3 </label> </div> </RadioGroup> ); } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/radio-group ``` ### Manual [#manual] <Steps> <Step> Install the following dependencies: ```bash pnpm install radix-ui ``` </Step> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the RadioGroup component into your `components/ui/RadioGroup.tsx` file. ```tsx "use client"; import * as React from "react"; import { RadioGroup as RadioGroupPrimitive } from "radix-ui"; import { cn } from "@/utils/class-names"; function RadioGroup({ className, ...props }: React.ComponentProps<typeof RadioGroupPrimitive.Root>) { return ( <RadioGroupPrimitive.Root data-slot="radio-group" className={cn(className, "cursor-pointer")} {...props} /> ); } function RadioGroupItem({ className, ...props }: React.ComponentProps<typeof RadioGroupPrimitive.Item>) { return ( <RadioGroupPrimitive.Item data-slot="radio-group-item" className={cn( className, "size-1.5 cursor-pointer rounded-full border border-gray-a6 hover:bg-accent-2" )} {...props} > <RadioGroupPrimitive.Indicator data-slot="radio-group-indicator" className="relative flex size-full items-center justify-center after:block after:size-0.5 after:rounded-full after:bg-accent-9" /> </RadioGroupPrimitive.Item> ); } export { RadioGroup, RadioGroupItem }; ``` </Step> </Steps> ## Usage [#usage] ### WithDefaultValue [#withdefaultvalue] ```tsx export const WithDefaultValue = () => { return ( <RadioGroup defaultValue="option-2" className="flex flex-col gap-0.5"> <div className="flex items-center gap-1"> <RadioGroupItem value="option-1" id="default-option-1" /> <label htmlFor="default-option-1" className="text-sm font-medium leading-none cursor-pointer" > Option 1 </label> </div> <div className="flex items-center gap-1"> <RadioGroupItem value="option-2" id="default-option-2" /> <label htmlFor="default-option-2" className="text-sm font-medium leading-none cursor-pointer" > Option 2 (default) </label> </div> <div className="flex items-center gap-1"> <RadioGroupItem value="option-3" id="default-option-3" /> <label htmlFor="default-option-3" className="text-sm font-medium leading-none cursor-pointer" > Option 3 </label> </div> </RadioGroup> ); }; ``` ### Disabled [#disabled] ```tsx export const Disabled = () => { const [value, setValue] = useState("option-1"); return ( <RadioGroup value={value} onValueChange={setValue} className="flex flex-col gap-0.5"> <div className="flex items-center gap-1"> <RadioGroupItem value="option-1" id="disabled-option-1" /> <label htmlFor="disabled-option-1" className="text-sm font-medium leading-none cursor-pointer" > Option 1 </label> </div> <div className="flex items-center gap-1"> <RadioGroupItem value="option-2" id="disabled-option-2" disabled /> <label htmlFor="disabled-option-2" className="text-sm font-medium leading-none text-gray-a8 cursor-not-allowed" > Option 2 (disabled) </label> </div> <div className="flex items-center gap-1"> <RadioGroupItem value="option-3" id="disabled-option-3" disabled /> <label htmlFor="disabled-option-3" className="text-sm font-medium leading-none text-gray-a8 cursor-not-allowed" > Option 3 (disabled) </label> </div> </RadioGroup> ); }; ``` ### WithDescription [#withdescription] ```tsx export const WithDescription = () => { const [value, setValue] = useState("email"); const options = [ { value: "email", label: "Email", description: "Receive notifications via email", }, { value: "sms", label: "SMS", description: "Receive notifications via text message", }, { value: "push", label: "Push", description: "Receive push notifications on your device", }, ]; return ( <RadioGroup value={value} onValueChange={setValue} className="flex flex-col gap-0.5"> {options.map((option) => ( <div key={option.value} className="flex items-start gap-1"> <RadioGroupItem value={option.value} id={option.value} /> <div className="flex flex-col gap-1"> <label htmlFor={option.value} className="text-sm font-medium leading-none cursor-pointer" > {option.label} </label> <p className="text-sm text-gray-a11 m-0">{option.description}</p> </div> </div> ))} </RadioGroup> ); }; ``` ### PaymentMethod [#paymentmethod] ```tsx export const PaymentMethod = () => { const [paymentMethod, setPaymentMethod] = useState("credit-card"); const methods = [ { value: "credit-card", label: "Credit Card", description: "Pay with your credit or debit card", }, { value: "paypal", label: "PayPal", description: "Pay securely with your PayPal account", }, { value: "bank-transfer", label: "Bank Transfer", description: "Direct transfer from your bank account", }, { value: "crypto", label: "Cryptocurrency", description: "Pay with Bitcoin, Ethereum, or other cryptocurrencies", }, ]; return ( <div className="flex flex-col gap-1"> <div className="text-sm font-semibold">Select payment method:</div> <RadioGroup value={paymentMethod} onValueChange={setPaymentMethod}> {methods.map((method) => ( <div key={method.value} className="flex items-start gap-1"> <RadioGroupItem value={method.value} id={method.value} /> <div className="flex flex-col gap-1"> <label htmlFor={method.value} className="text-sm font-medium leading-none cursor-pointer" > {method.label} </label> <p className="text-sm text-gray-a11 m-0">{method.description}</p> </div> </div> ))} </RadioGroup> {paymentMethod && ( <div className="mt-2 text-sm text-gray-a11"> Selected: {methods.find((m) => m.value === paymentMethod)?.label} </div> )} </div> ); }; ``` ### NotificationPreferences [#notificationpreferences] ```tsx export const NotificationPreferences = () => { const [frequency, setFrequency] = useState("daily"); const frequencies = [ { value: "realtime", label: "Real-time", description: "Get notified immediately when something happens", }, { value: "daily", label: "Daily digest", description: "Receive a summary once per day", }, { value: "weekly", label: "Weekly digest", description: "Receive a summary once per week", }, { value: "never", label: "Never", description: "Don't send me any notifications", }, ]; return ( <div className="flex flex-col gap-1"> <div className="text-sm font-semibold"> How often would you like to receive notifications? </div> <RadioGroup value={frequency} onValueChange={setFrequency}> {frequencies.map((freq) => ( <div key={freq.value} className="flex items-start gap-1"> <RadioGroupItem value={freq.value} id={freq.value} /> <div className="flex flex-col gap-1"> <label htmlFor={freq.value} className="text-sm font-medium leading-none cursor-pointer" > {freq.label} </label> <p className="text-sm text-gray-a11 m-0">{freq.description}</p> </div> </div> ))} </RadioGroup> </div> ); }; ``` ### Horizontal [#horizontal] ```tsx export const Horizontal = () => { const [value, setValue] = useState("small"); return ( <RadioGroup value={value} onValueChange={setValue} className="flex flex-row gap-0.5" > <div className="flex items-center gap-1"> <RadioGroupItem value="small" id="size-small" /> <label htmlFor="size-small" className="text-sm font-medium leading-none cursor-pointer" > Small </label> </div> <div className="flex items-center gap-1"> <RadioGroupItem value="medium" id="size-medium" /> <label htmlFor="size-medium" className="text-sm font-medium leading-none cursor-pointer" > Medium </label> </div> <div className="flex items-center gap-1"> <RadioGroupItem value="large" id="size-large" /> <label htmlFor="size-large" className="text-sm font-medium leading-none cursor-pointer" > Large </label> </div> </RadioGroup> ); }; ``` # Rating (/docs/components/rating) ## Preview [#preview] <ComponentPreview name="rating-demo" description="A star rating that works with the keyboard."> ```tsx import { Rating } from "@/components/ui/Rating"; export function RatingDemo() { return <Rating defaultValue={3} />; } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/rating ``` ### Manual [#manual] <Steps> <Step> Install the following dependencies: ```bash pnpm install @radix-ui/react-icons ``` </Step> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the Rating component into your `components/ui/Rating.tsx` file. ```tsx "use client"; import * as React from "react"; import { StarFilledIcon, StarIcon } from "@radix-ui/react-icons"; import { cn } from "@/utils/class-names"; function Rating({ className, value, defaultValue = 0, max = 5, onValueChange, label = "Rating", readOnly = false, }: { className?: string; value?: number; defaultValue?: number; max?: number; onValueChange?: (value: number) => void; label?: string; readOnly?: boolean; }) { const [uncontrolled, setUncontrolled] = React.useState(defaultValue); const current = value ?? uncontrolled; const set = (next: number) => { if (readOnly) return; if (value === undefined) setUncontrolled(next); onValueChange?.(next); }; return ( <div role="radiogroup" aria-label={label} data-slot="rating" className={cn("inline-flex items-center gap-0.5", className)} onKeyDown={(event) => { if (readOnly) return; if (event.key === "ArrowRight" || event.key === "ArrowUp") { event.preventDefault(); set(Math.min(max, current + 1 || 1)); } else if (event.key === "ArrowLeft" || event.key === "ArrowDown") { event.preventDefault(); set(Math.max(1, current - 1)); } }} > {Array.from({ length: max }, (_, index) => { const score = index + 1; const filled = score <= current; const Icon = filled ? StarFilledIcon : StarIcon; return ( <button key={score} type="button" role="radio" aria-checked={current === score} aria-label={`${score} of ${max}`} disabled={readOnly} className="inline-flex size-3 items-center justify-center rounded-sm text-accent-9 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent-8" onClick={() => set(score)} > <Icon className="icon" /> </button> ); })} </div> ); } export { Rating }; ``` </Step> </Steps> # Relative Time Card (/docs/components/relative-time-card) ## Preview [#preview] <ComponentPreview name="relative-time-card-demo" description="A relative time with the absolute date beside it."> ```tsx import { RelativeTimeCard } from "@/components/ui/RelativeTimeCard"; export function RelativeTimeCardDemo() { return <RelativeTimeCard date={new Date(Date.now() - 2 * 24 * 60 * 60 * 1000)} />; ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/relative-time-card ``` ### Manual [#manual] <Steps> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the RelativeTimeCard component into your `components/ui/RelativeTimeCard.tsx` file. ```tsx "use client"; import * as React from "react"; import { cn } from "@/utils/class-names"; function relativeLabel(date: Date, now = new Date()) { const minutes = Math.round((date.getTime() - now.getTime()) / 60000); const abs = Math.abs(minutes); const formatter = new Intl.RelativeTimeFormat(undefined, { numeric: "auto" }); if (abs < 60) return formatter.format(minutes, "minute"); const hours = Math.round(minutes / 60); if (Math.abs(hours) < 24) return formatter.format(hours, "hour"); return formatter.format(Math.round(hours / 24), "day"); } function RelativeTimeCard({ className, date, label = "Time", }: { className?: string; date: Date; label?: string; }) { const time = date.getTime(); const iso = new Date(time).toISOString(); const [relative, setRelative] = React.useState(iso); const [absolute, setAbsolute] = React.useState(iso); React.useEffect(() => { const value = new Date(time); setRelative(relativeLabel(value)); setAbsolute(value.toLocaleString()); }, [time]); return ( <span data-slot="relative-time-card" className={cn("inline-flex flex-col gap-0.5", className)}> <time dateTime={iso} aria-label={label}> {relative} </time> <span className="rounded-sm border border-gray-6 bg-gray-2 px-1 py-0.5 text-gray-11">{absolute}</span> </span> ); } export { RelativeTimeCard }; ``` </Step> </Steps> # Resizable (/docs/components/resizable) ## Preview [#preview] <ComponentPreview name="resizable-demo" description="Panels that resize by drag or keyboard."> ```tsx import { ResizableHandle, ResizablePanel, ResizablePanelGroup, } from "@/components/ui/Resizable"; export function ResizableDemo() { return ( <div className="h-16 w-full overflow-hidden rounded-md border border-gray-6"> <ResizablePanelGroup direction="horizontal" className="h-full"> <ResizablePanel defaultSize={50} minSize={20}> <div className="flex h-full items-center justify-center p-1 text-sm text-gray-12"> One </div> </ResizablePanel> <ResizableHandle withHandle /> <ResizablePanel defaultSize={50} minSize={20}> <div className="flex h-full items-center justify-center p-1 text-sm text-gray-12"> Two </div> </ResizablePanel> </ResizablePanelGroup> </div> ); } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/resizable ``` ### Manual [#manual] <Steps> <Step> Install the following dependencies: ```bash pnpm install @radix-ui/react-icons react-resizable-panels ``` </Step> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the Resizable component into your `components/ui/Resizable.tsx` file. ```tsx "use client"; /** * @description Resizable panels. Drag the handle; keyboard users resize from the focused separator. / import as React from "react"; import { DragHandleDots2Icon } from "@radix-ui/react-icons"; import * as ResizablePrimitive from "react-resizable-panels"; import { cn } from "@/utils/class-names"; function ResizablePanelGroup({ className, ...props }: React.ComponentProps<typeof ResizablePrimitive.PanelGroup>) { return ( <ResizablePrimitive.PanelGroup data-slot="resizable-panel-group" className={cn( "flex h-full w-full data-[panel-group-direction=vertical]:flex-col", className, )} {...props} /> ); } const ResizablePanel = ResizablePrimitive.Panel; function ResizableHandle({ withHandle, className, ...props }: React.ComponentProps<typeof ResizablePrimitive.PanelResizeHandle> & { withHandle?: boolean; }) { return ( <ResizablePrimitive.PanelResizeHandle data-slot="resizable-handle" className={cn( "relative flex w-px items-center justify-center bg-gray-6 before:absolute before:inset-y-0 before:left-1/2 before:w-1 before:-translate-x-1/2 focus-visible:outline-2 focus-visible:outline-accent-8 data-[panel-group-direction=vertical]:h-px data-[panel-group-direction=vertical]:w-full data-[panel-group-direction=vertical]:before:left-0 data-[panel-group-direction=vertical]:before:h-1 data-[panel-group-direction=vertical]:before:w-full data-[panel-group-direction=vertical]:before:translate-x-0 data-[panel-group-direction=vertical]:before:-translate-y-1/2 data-[panel-group-direction=vertical]:[&>div]:rotate-90", className, )} {...props} > {withHandle ? ( <div className="z-10 flex h-3 w-2 items-center justify-center rounded-sm border border-gray-6 bg-gray-2"> <DragHandleDots2Icon className="icon" /> </div> ) : null} </ResizablePrimitive.PanelResizeHandle> ); } export { ResizablePanelGroup, ResizablePanel, ResizableHandle }; ``` </Step> </Steps> ## Usage [#usage] ### Vertical [#vertical] ```tsx export const Vertical = () => { return ( <div className="h-16 w-full overflow-hidden rounded-md border border-gray-6"> <ResizablePanelGroup direction="vertical" className="h-full"> <ResizablePanel defaultSize={50}> <div className="flex h-full items-center justify-center p-1 text-sm"> Top </div> </ResizablePanel> <ResizableHandle withHandle /> <ResizablePanel defaultSize={50}> <div className="flex h-full items-center justify-center p-1 text-sm"> Bottom </div> </ResizablePanel> </ResizablePanelGroup> </div> ); }; ``` # Responsive Dialog (/docs/components/responsive-dialog) ## Preview [#preview] <ComponentPreview name="responsive-dialog-demo" description="A dialog on desktop and a drawer on mobile, sharing one API."> ```tsx import { Button } from "@/components/ui/Button"; import { ResponsiveDialog, ResponsiveDialogClose, ResponsiveDialogContent, ResponsiveDialogDescription, ResponsiveDialogFooter, ResponsiveDialogHeader, ResponsiveDialogTitle, ResponsiveDialogTrigger, } from "@/components/ui/ResponsiveDialog"; export function ResponsiveDialogDemo() { return ( <ResponsiveDialog> <ResponsiveDialogTrigger asChild> <Button variant="pill">Open</Button> </ResponsiveDialogTrigger> <ResponsiveDialogContent className="data-[variant=dialog]:max-w-md"> <ResponsiveDialogHeader> <ResponsiveDialogTitle>Edit profile</ResponsiveDialogTitle> <ResponsiveDialogDescription> Dialog on desktop, drawer on mobile. Resize the viewport to switch. </ResponsiveDialogDescription> </ResponsiveDialogHeader> <p className="text-sm text-gray-11 p-1"> Use <code className="text-xs">data-variant</code> to style each surface. </p> <ResponsiveDialogFooter className="gap-1 p-1"> <ResponsiveDialogClose asChild> <Button variant="pill">Cancel</Button> </ResponsiveDialogClose> <Button variant="fill">Save</Button> </ResponsiveDialogFooter> </ResponsiveDialogContent> </ResponsiveDialog> ) } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/responsive-dialog ``` ### Manual [#manual] <Steps> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the dialog component into your `components/ui/Dialog.tsx` file. ```tsx /** * @description A window overlaid on the primary content, rendering content in a layer above the page. */ import { Dialog as DialogPrimitive } from "radix-ui"; import { Cross2Icon } from "@radix-ui/react-icons"; import { cn } from "@/utils/class-names"; import { Button } from "@/components/ui/Button"; function Dialog({ ...props }: React.ComponentProps<typeof DialogPrimitive.Root>) { return <DialogPrimitive.Root data-slot="dialog" {...props} />; } function DialogTrigger({ ...props }: React.ComponentProps<typeof DialogPrimitive.Trigger>) { return <DialogPrimitive.Trigger data-slot="dialog-trigger" {...props} />; } function DialogPortal({ ...props }: React.ComponentProps<typeof DialogPrimitive.Portal>) { return <DialogPrimitive.Portal data-slot="dialog-portal" {...props} />; } function DialogClose({ ...props }: React.ComponentProps<typeof DialogPrimitive.Close>) { return <DialogPrimitive.Close data-slot="dialog-close" {...props} />; } function DialogOverlay({ className, ...props }: React.ComponentProps<typeof DialogPrimitive.Overlay>) { return ( <DialogPrimitive.Overlay data-slot="dialog-overlay" className={cn( "aura-overlay z-50", className )} {...props} /> ); } function DialogContent({ className, children, ...props }: React.ComponentProps<typeof DialogPrimitive.Content>) { return ( <DialogPortal data-slot="dialog-portal"> <DialogOverlay /> <DialogPrimitive.Content data-slot="dialog-content" className={cn( "smash fixed left-1/2 top-1/2 max-h-[85vh] w-[90vw] -translate-x-1/2 -translate-y-1/2 bg-gray-1 p-2 rounded-md z-50 data-[state=open]:animate-content-show border border-gray-a6", className )} {...props} > {children} <DialogPrimitive.Close asChild> <Button mode="link" className="absolute top-0.5 right-0.5"> <Cross2Icon /> </Button> </DialogPrimitive.Close> </DialogPrimitive.Content> </DialogPortal> ); } function DialogHeader({ ...props }: React.ComponentProps<"div">) { return <div data-slot="dialog-header" {...props} />; } function DialogFooter({ className, ...props }: React.ComponentProps<"div">) { return ( <div data-slot="dialog-footer" className={cn("flex justify-end gap-1", className)} {...props} /> ); } function DialogTitle({ ...props }: React.ComponentProps<typeof DialogPrimitive.Title>) { return <DialogPrimitive.Title data-slot="dialog-title" {...props} />; } function DialogDescription({ ...props }: React.ComponentProps<typeof DialogPrimitive.Description>) { return ( <DialogPrimitive.Description data-slot="dialog-description" {...props} /> ); } export { Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, }; ``` </Step> <Step> Copy and paste the drawer component into your `components/ui/Drawer.tsx` file. ```tsx "use client"; /** * @description A drawer component that slides in from the edge of the screen. / import as React from "react"; import { Drawer as DrawerPrimitive } from "vaul"; import { cn } from "@/utils/class-names"; function Drawer({ ...props }: React.ComponentProps<typeof DrawerPrimitive.Root>) { return <DrawerPrimitive.Root data-slot="drawer" {...props} />; } function DrawerTrigger({ ...props }: React.ComponentProps<typeof DrawerPrimitive.Trigger>) { return <DrawerPrimitive.Trigger data-slot="drawer-trigger" {...props} />; } function DrawerPortal({ ...props }: React.ComponentProps<typeof DrawerPrimitive.Portal>) { return <DrawerPrimitive.Portal data-slot="drawer-portal" {...props} />; } function DrawerClose({ ...props }: React.ComponentProps<typeof DrawerPrimitive.Close>) { return <DrawerPrimitive.Close data-slot="drawer-close" {...props} />; } function DrawerOverlay({ className, ...props }: React.ComponentProps<typeof DrawerPrimitive.Overlay>) { return ( <DrawerPrimitive.Overlay data-slot="drawer-overlay" className={cn("aura-overlay z-50", className)} {...props} /> ); } function DrawerContent({ className, children, ...props }: React.ComponentProps<typeof DrawerPrimitive.Content>) { return ( <DrawerPortal data-slot="drawer-portal"> <DrawerOverlay /> <DrawerPrimitive.Content data-slot="drawer-content" className={cn( "fixed inset-x-0 bottom-0 z-50 mt-8 flex h-auto flex-col rounded-t-[10px] border border-gray-6 bg-gray-1", className )} {...props} > <div className="mx-auto mt-1 h-0.5 w-8 rounded-full bg-gray-3" /> {children} </DrawerPrimitive.Content> </DrawerPortal> ); } function DrawerHeader({ className, ...props }: React.ComponentProps<"div">) { return ( <div data-slot="drawer-header" className={cn("grid gap-0.5 p-1.5 text-center sm:text-left", className)} {...props} /> ); } function DrawerFooter({ className, ...props }: React.ComponentProps<"div">) { return ( <div data-slot="drawer-footer" className={cn("mt-auto flex flex-col gap-1 p-1.5", className)} {...props} /> ); } function DrawerTitle({ className, ...props }: React.ComponentProps<typeof DrawerPrimitive.Title>) { return ( <DrawerPrimitive.Title data-slot="drawer-title" className={cn( "text-lg font-semibold leading-none tracking-tight text-gray-12", className )} {...props} /> ); } function DrawerDescription({ className, ...props }: React.ComponentProps<typeof DrawerPrimitive.Description>) { return ( <DrawerPrimitive.Description data-slot="drawer-description" className={cn("text-sm text-gray-11", className)} {...props} /> ); } export { Drawer, DrawerPortal, DrawerOverlay, DrawerTrigger, DrawerClose, DrawerContent, DrawerHeader, DrawerFooter, DrawerTitle, DrawerDescription, }; ``` </Step> <Step> Copy and paste the use as ref hook into your `hooks/use-as-ref.ts` file. ```ts import * as React from "react"; import { useIsomorphicLayoutEffect } from "@/hooks/use-isomorphic-layout-effect"; function useAsRef<T>(props: T) { const ref = React.useRef<T>(props); useIsomorphicLayoutEffect(() => { ref.current = props; }); return ref; } export { useAsRef }; ``` </Step> <Step> Copy and paste the use isomorphic layout effect hook into your `hooks/use-isomorphic-layout-effect.ts` file. ```ts import * as React from "react"; const useIsomorphicLayoutEffect = typeof window !== "undefined" ? React.useLayoutEffect : React.useEffect; export { useIsomorphicLayoutEffect }; ``` </Step> <Step> Copy and paste the use lazy ref hook into your `hooks/use-lazy-ref.ts` file. ```ts import * as React from "react"; function useLazyRef<T>(fn: () => T) { const ref = React.useRef<T | null>(null); if (ref.current === null) { ref.current = fn(); } return ref as React.RefObject<T>; } export { useLazyRef }; ``` </Step> <Step> Copy and paste the use mobile hook into your `hooks/use-mobile.ts` file. ```ts import * as React from "react" const MOBILE_BREAKPOINT = 768 export function useIsMobile(breakpoint = MOBILE_BREAKPOINT) { const [isMobile, setIsMobile] = React.useState<boolean | undefined>(undefined) React.useEffect(() => { const mql = window.matchMedia(`(max-width: ${breakpoint - 1}px)`) const onChange = () => { setIsMobile(window.innerWidth < breakpoint) } mql.addEventListener("change", onChange) setIsMobile(window.innerWidth < breakpoint) return () => mql.removeEventListener("change", onChange) }, [breakpoint]) return !!isMobile } ``` </Step> <Step> Copy and paste the ResponsiveDialog component into your `components/ui/ResponsiveDialog.tsx` file. ```tsx "use client"; /** * @description A dialog on desktop and a drawer on mobile, sharing one API. / import as React from "react"; import { cn } from "@/utils/class-names"; import { useAsRef } from "@/hooks/use-as-ref"; import { useIsomorphicLayoutEffect } from "@/hooks/use-isomorphic-layout-effect"; import { useLazyRef } from "@/hooks/use-lazy-ref"; import { useIsMobile } from "@/hooks/use-mobile"; import { Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, } from "@/components/ui/Dialog"; import { Drawer, DrawerClose, DrawerContent, DrawerDescription, DrawerFooter, DrawerHeader, DrawerOverlay, DrawerPortal, DrawerTitle, DrawerTrigger, } from "@/components/ui/Drawer"; const ROOT_NAME = "ResponsiveDialog"; interface StoreState { open: boolean; isMobile: boolean; } interface Store { subscribe: (callback: () => void) => () => void; getState: () => StoreState; setState: <K extends keyof StoreState>(key: K, value: StoreState[K]) => void; notify: () => void; } const StoreContext = React.createContext<Store | null>(null); function useStore<T>( selector: (state: StoreState) => T, ogStore?: Store | null ): T { const contextStore = React.useContext(StoreContext); const store = ogStore ?? contextStore; if (!store) { throw new Error(`\`useStore\` must be used within \`${ROOT_NAME}\``); } const getSnapshot = React.useCallback( () => selector(store.getState()), [store, selector] ); return React.useSyncExternalStore(store.subscribe, getSnapshot, getSnapshot); } interface ResponsiveDialogProps extends React.ComponentProps<typeof Dialog> { breakpoint?: number; } function ResponsiveDialog({ breakpoint = 768, open: openProp, defaultOpen = false, onOpenChange: onOpenChangeProp, ...props }: ResponsiveDialogProps) { const isMobile = useIsMobile(breakpoint); const listenersRef = useLazyRef(() => new Set<() => void>()); const stateRef = useLazyRef<StoreState>(() => ({ open: openProp ?? defaultOpen, isMobile, })); const onOpenChangeRef = useAsRef(onOpenChangeProp); const store = React.useMemo<Store>(() => { return { subscribe: (cb) => { listenersRef.current.add(cb); return () => { listenersRef.current.delete(cb); }; }, getState: () => stateRef.current, setState: (key, value) => { if (Object.is(stateRef.current[key], value)) return; if (key === "open" && typeof value === "boolean") { stateRef.current.open = value; onOpenChangeRef.current?.(value); } else { stateRef.current[key] = value; } store.notify(); }, notify: () => { for (const cb of listenersRef.current) { cb(); } }, }; }, [listenersRef, stateRef, onOpenChangeRef]); if (stateRef.current.isMobile !== isMobile) { stateRef.current.isMobile = isMobile; } const open = useStore((state) => state.open, store); useIsomorphicLayoutEffect(() => { if (openProp !== undefined) { store.setState("open", openProp); } }, [openProp]); const onOpenChange = React.useCallback( (value: boolean) => { store.setState("open", value); }, [store] ); if (isMobile) { return ( <StoreContext.Provider value={store}> <Drawer open={open} onOpenChange={onOpenChange} {...props} /> </StoreContext.Provider> ); } return ( <StoreContext.Provider value={store}> <Dialog open={open} onOpenChange={onOpenChange} {...props} /> </StoreContext.Provider> ); } function ResponsiveDialogTrigger({ ...props }: React.ComponentProps<typeof DialogTrigger>) { const isMobile = useStore((state) => state.isMobile); if (isMobile) { return <DrawerTrigger data-variant="drawer" {...props} />; } return <DialogTrigger data-variant="dialog" {...props} />; } function ResponsiveDialogClose({ ...props }: React.ComponentProps<typeof DialogClose>) { const isMobile = useStore((state) => state.isMobile); if (isMobile) { return <DrawerClose data-variant="drawer" {...props} />; } return <DialogClose data-variant="dialog" {...props} />; } function ResponsiveDialogPortal({ ...props }: React.ComponentProps<typeof DialogPortal>) { const isMobile = useStore((state) => state.isMobile); if (isMobile) { return <DrawerPortal data-variant="drawer" {...props} />; } return <DialogPortal data-variant="dialog" {...props} />; } function ResponsiveDialogOverlay({ ...props }: React.ComponentProps<typeof DialogOverlay>) { const isMobile = useStore((state) => state.isMobile); if (isMobile) { return <DrawerOverlay data-variant="drawer" {...props} />; } return <DialogOverlay data-variant="dialog" {...props} />; } function ResponsiveDialogContent({ className, ...props }: React.ComponentProps<typeof DialogContent>) { const isMobile = useStore((state) => state.isMobile); if (isMobile) { return ( <DrawerContent data-variant="drawer" className={cn("px-1.5 pb-1.5", className)} {...props} /> ); } return ( <DialogContent data-variant="dialog" className={className} {...props} /> ); } function ResponsiveDialogHeader({ ...props }: React.ComponentProps<typeof DialogHeader>) { const isMobile = useStore((state) => state.isMobile); if (isMobile) { return <DrawerHeader data-variant="drawer" {...props} />; } return <DialogHeader data-variant="dialog" {...props} />; } function ResponsiveDialogFooter({ className, ...props }: React.ComponentProps<typeof DialogFooter>) { const isMobile = useStore((state) => state.isMobile); if (isMobile) { return ( <DrawerFooter data-variant="drawer" className={cn( "data-[variant=drawer]:flex-col", className )} {...props} /> ); } return ( <DialogFooter data-variant="dialog" className={cn("data-[variant=dialog]:flex-row", className)} {...props} /> ); } function ResponsiveDialogTitle({ ...props }: React.ComponentProps<typeof DialogTitle>) { const isMobile = useStore((state) => state.isMobile); if (isMobile) { return <DrawerTitle data-variant="drawer" {...props} />; } return <DialogTitle data-variant="dialog" {...props} />; } function ResponsiveDialogDescription({ ...props }: React.ComponentProps<typeof DialogDescription>) { const isMobile = useStore((state) => state.isMobile); if (isMobile) { return <DrawerDescription data-variant="drawer" {...props} />; } return <DialogDescription data-variant="dialog" {...props} />; } export { ResponsiveDialog, ResponsiveDialogClose, ResponsiveDialogContent, ResponsiveDialogDescription, ResponsiveDialogFooter, ResponsiveDialogHeader, ResponsiveDialogOverlay, ResponsiveDialogPortal, ResponsiveDialogTitle, ResponsiveDialogTrigger, }; ``` </Step> </Steps> ## Usage [#usage] ### Confirmation [#confirmation] ```tsx export const Confirmation = () => ( <ResponsiveDialog> <ResponsiveDialogTrigger asChild> <Button variant="pill">Delete project</Button> </ResponsiveDialogTrigger> <ResponsiveDialogContent className="data-[variant=dialog]:max-w-sm"> <ResponsiveDialogHeader> <ResponsiveDialogTitle>Delete this project?</ResponsiveDialogTitle> <ResponsiveDialogDescription> This action cannot be undone. The project and its resources will be permanently removed. </ResponsiveDialogDescription> </ResponsiveDialogHeader> <ResponsiveDialogFooter className="gap-1 p-1 data-[variant=drawer]:flex-col data-[variant=dialog]:flex-row data-[variant=dialog]:justify-end"> <ResponsiveDialogClose asChild> <Button variant="pill">Cancel</Button> </ResponsiveDialogClose> <ResponsiveDialogClose asChild> <Button variant="fill">Delete</Button> </ResponsiveDialogClose> </ResponsiveDialogFooter> </ResponsiveDialogContent> </ResponsiveDialog> ) ``` ### CustomBreakpoint [#custombreakpoint] ```tsx export const CustomBreakpoint = () => ( <ResponsiveDialog breakpoint={1024}> <ResponsiveDialogTrigger asChild> <Button variant="pill">Breakpoint 1024</Button> </ResponsiveDialogTrigger> <ResponsiveDialogContent> <ResponsiveDialogHeader> <ResponsiveDialogTitle>Custom breakpoint</ResponsiveDialogTitle> <ResponsiveDialogDescription> Switches to drawer below 1024px instead of the default 768px. </ResponsiveDialogDescription> </ResponsiveDialogHeader> <ResponsiveDialogFooter className="p-1"> <ResponsiveDialogClose asChild> <Button variant="fill">Got it</Button> </ResponsiveDialogClose> </ResponsiveDialogFooter> </ResponsiveDialogContent> </ResponsiveDialog> ) ``` # Responsive Dropdown Menu (/docs/components/responsive-dropdown-menu) ## Preview [#preview] <ComponentPreview name="responsive-dropdown-menu-demo" description="A dropdown menu on desktop and a stacked drawer for nested menus on mobile."> ```tsx import { Button } from "@/components/ui/Button"; import { ResponsiveDropdownMenu, ResponsiveDropdownMenuContent, ResponsiveDropdownMenuGroup, ResponsiveDropdownMenuItem, ResponsiveDropdownMenuLabel, ResponsiveDropdownMenuSeparator, ResponsiveDropdownMenuShortcut, ResponsiveDropdownMenuSub, ResponsiveDropdownMenuSubContent, ResponsiveDropdownMenuSubTrigger, ResponsiveDropdownMenuTrigger, } from "@/components/ui/ResponsiveDropdownMenu"; export function ResponsiveDropdownMenuDemo() { return ( <ResponsiveDropdownMenu> <ResponsiveDropdownMenuTrigger asChild> <Button variant="menu">Open menu</Button> </ResponsiveDropdownMenuTrigger> <ResponsiveDropdownMenuContent mobileTitle="Account" className="data-[variant=dropdown]:w-20" > <ResponsiveDropdownMenuLabel>My account</ResponsiveDropdownMenuLabel> <ResponsiveDropdownMenuSeparator /> <ResponsiveDropdownMenuGroup> <ResponsiveDropdownMenuItem> Profile <ResponsiveDropdownMenuShortcut>⇧⌘P</ResponsiveDropdownMenuShortcut> </ResponsiveDropdownMenuItem> <ResponsiveDropdownMenuItem>Notifications</ResponsiveDropdownMenuItem> <ResponsiveDropdownMenuSub> <ResponsiveDropdownMenuSubTrigger> Share </ResponsiveDropdownMenuSubTrigger> <ResponsiveDropdownMenuSubContent> <ResponsiveDropdownMenuItem>Copy link</ResponsiveDropdownMenuItem> <ResponsiveDropdownMenuSub> <ResponsiveDropdownMenuSubTrigger> Send to team </ResponsiveDropdownMenuSubTrigger> <ResponsiveDropdownMenuSubContent> <ResponsiveDropdownMenuItem>Design</ResponsiveDropdownMenuItem> <ResponsiveDropdownMenuItem> Engineering </ResponsiveDropdownMenuItem> </ResponsiveDropdownMenuSubContent> </ResponsiveDropdownMenuSub> </ResponsiveDropdownMenuSubContent> </ResponsiveDropdownMenuSub> </ResponsiveDropdownMenuGroup> <ResponsiveDropdownMenuSeparator /> <ResponsiveDropdownMenuItem>Log out</ResponsiveDropdownMenuItem> </ResponsiveDropdownMenuContent> </ResponsiveDropdownMenu> ) } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/responsive-dropdown-menu ``` ### Manual [#manual] <Steps> <Step> Install the following dependencies: ```bash pnpm install @radix-ui/react-icons @radix-ui/react-slot ``` </Step> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the drawer component into your `components/ui/Drawer.tsx` file. ```tsx "use client"; /** * @description A drawer component that slides in from the edge of the screen. / import as React from "react"; import { Drawer as DrawerPrimitive } from "vaul"; import { cn } from "@/utils/class-names"; function Drawer({ ...props }: React.ComponentProps<typeof DrawerPrimitive.Root>) { return <DrawerPrimitive.Root data-slot="drawer" {...props} />; } function DrawerTrigger({ ...props }: React.ComponentProps<typeof DrawerPrimitive.Trigger>) { return <DrawerPrimitive.Trigger data-slot="drawer-trigger" {...props} />; } function DrawerPortal({ ...props }: React.ComponentProps<typeof DrawerPrimitive.Portal>) { return <DrawerPrimitive.Portal data-slot="drawer-portal" {...props} />; } function DrawerClose({ ...props }: React.ComponentProps<typeof DrawerPrimitive.Close>) { return <DrawerPrimitive.Close data-slot="drawer-close" {...props} />; } function DrawerOverlay({ className, ...props }: React.ComponentProps<typeof DrawerPrimitive.Overlay>) { return ( <DrawerPrimitive.Overlay data-slot="drawer-overlay" className={cn("aura-overlay z-50", className)} {...props} /> ); } function DrawerContent({ className, children, ...props }: React.ComponentProps<typeof DrawerPrimitive.Content>) { return ( <DrawerPortal data-slot="drawer-portal"> <DrawerOverlay /> <DrawerPrimitive.Content data-slot="drawer-content" className={cn( "fixed inset-x-0 bottom-0 z-50 mt-8 flex h-auto flex-col rounded-t-[10px] border border-gray-6 bg-gray-1", className )} {...props} > <div className="mx-auto mt-1 h-0.5 w-8 rounded-full bg-gray-3" /> {children} </DrawerPrimitive.Content> </DrawerPortal> ); } function DrawerHeader({ className, ...props }: React.ComponentProps<"div">) { return ( <div data-slot="drawer-header" className={cn("grid gap-0.5 p-1.5 text-center sm:text-left", className)} {...props} /> ); } function DrawerFooter({ className, ...props }: React.ComponentProps<"div">) { return ( <div data-slot="drawer-footer" className={cn("mt-auto flex flex-col gap-1 p-1.5", className)} {...props} /> ); } function DrawerTitle({ className, ...props }: React.ComponentProps<typeof DrawerPrimitive.Title>) { return ( <DrawerPrimitive.Title data-slot="drawer-title" className={cn( "text-lg font-semibold leading-none tracking-tight text-gray-12", className )} {...props} /> ); } function DrawerDescription({ className, ...props }: React.ComponentProps<typeof DrawerPrimitive.Description>) { return ( <DrawerPrimitive.Description data-slot="drawer-description" className={cn("text-sm text-gray-11", className)} {...props} /> ); } export { Drawer, DrawerPortal, DrawerOverlay, DrawerTrigger, DrawerClose, DrawerContent, DrawerHeader, DrawerFooter, DrawerTitle, DrawerDescription, }; ``` </Step> <Step> Copy and paste the dropdown menu component into your `components/ui/DropdownMenu.tsx` file. ```tsx "use client"; /** * @description Displays a menu of actions or options triggered by a button. / import as React from "react"; import { DropdownMenu as DropdownMenuRadix } from "radix-ui"; import { CheckIcon, ChevronRightIcon, CircleIcon, DotFilledIcon, } from "@radix-ui/react-icons"; import { cn } from "@/utils/class-names"; function DropdownMenu({ ...props }: React.ComponentProps<typeof DropdownMenuRadix.Root>) { return <DropdownMenuRadix.Root data-slot="dropdown-menu" {...props} />; } function DropdownMenuPortal({ ...props }: React.ComponentProps<typeof DropdownMenuRadix.Portal>) { return ( <DropdownMenuRadix.Portal data-slot="dropdown-menu-portal" {...props} /> ); } function DropdownMenuTrigger({ className, ...props }: React.ComponentProps<typeof DropdownMenuRadix.Trigger>) { return ( <DropdownMenuRadix.Trigger data-slot="dropdown-menu-trigger" className={cn(className)} {...props} /> ); } function DropdownMenuContent({ className, ...props }: React.ComponentProps<typeof DropdownMenuRadix.Content>) { return ( <DropdownMenuRadix.Portal> <DropdownMenuRadix.Content data-slot="dropdown-menu-content" collisionPadding={8} className={cn( className, "z-50 origin-(--radix-dropdown-menu-content-transform-origin) bg-gray-1 border border-gray-a6 rounded-sm relative shadow-md data-[state=open]:animate-popover-show data-[state=closed]:animate-popover-hide" )} {...props} /> </DropdownMenuRadix.Portal> ); } function DropdownMenuGroup({ ...props }: React.ComponentProps<typeof DropdownMenuRadix.Group>) { return <DropdownMenuRadix.Group data-slot="dropdown-menu-group" {...props} />; } function DropdownMenuItem({ className, ...props }: React.ComponentProps<typeof DropdownMenuRadix.Item>) { return ( <DropdownMenuRadix.Item data-slot="dropdown-menu-item" className={cn( className, "p-0.5 px-2 hover:bg-accent-3 flex relative cursor-pointer" )} {...props} /> ); } function DropdownMenuCheckboxItem({ children, className, ...props }: React.ComponentProps<typeof DropdownMenuRadix.CheckboxItem>) { return ( <DropdownMenuRadix.CheckboxItem data-slot="dropdown-menu-checkbox-item" className={cn( className, "p-0.5 px-2 hover:bg-accent-3 flex relative cursor-pointer" )} {...props} > <span className="absolute left-0.5 top-0 bottom-0 items-center flex justify-center"> <DropdownMenuRadix.ItemIndicator> <CheckIcon className="text-accent-9" /> </DropdownMenuRadix.ItemIndicator> </span> {children} </DropdownMenuRadix.CheckboxItem> ); } function DropdownMenuRadioGroup({ className, ...props }: React.ComponentProps<typeof DropdownMenuRadix.RadioGroup>) { return ( <DropdownMenuRadix.RadioGroup data-slot="dropdown-menu-radio-group" className={cn(className)} {...props} /> ); } function DropdownMenuRadioItem({ children, className, ...props }: React.ComponentProps<typeof DropdownMenuRadix.RadioItem>) { return ( <DropdownMenuRadix.RadioItem data-slot="dropdown-menu-radio-item" className={cn( className, "p-0.5 px-2 hover:bg-accent-3 flex relative cursor-pointer" )} {...props} > <span className="absolute left-0.5 top-0 bottom-0 items-center flex justify-center"> <DropdownMenuRadix.ItemIndicator> <DotFilledIcon className="fill-current text-accent-9" /> </DropdownMenuRadix.ItemIndicator> </span> {children} </DropdownMenuRadix.RadioItem> ); } function DropdownMenuLabel({ className, ...props }: React.ComponentProps<typeof DropdownMenuRadix.Label>) { return ( <DropdownMenuRadix.Label data-slot="dropdown-menu-label" className={cn(className, "p-0.5 px-2 text-gray-12")} {...props} /> ); } function DropdownMenuSeparator({ className, ...props }: React.ComponentProps<typeof DropdownMenuRadix.Separator>) { return ( <DropdownMenuRadix.Separator data-slot="dropdown-menu-separator" className={cn(className, "m-0.6 h-px bg-gray-a6")} {...props} /> ); } function DropdownMenuShortcut({ ...props }: React.ComponentProps<"span">) { return <span data-slot="dropdown-menu-shortcut" {...props} />; } function DropdownMenuSub({ ...props }: React.ComponentProps<typeof DropdownMenuRadix.Sub>) { return <DropdownMenuRadix.Sub data-slot="dropdown-menu-sub" {...props} />; } function DropdownMenuSubTrigger({ children, className, ...props }: React.ComponentProps<typeof DropdownMenuRadix.SubTrigger>) { return ( <DropdownMenuRadix.SubTrigger data-slot="dropdown-menu-sub-trigger" className={cn( className, "p-0.5 px-2 hover:bg-accent-3 flex relative cursor-pointer" )} {...props} > {children} <div className="absolute right-0.5 top-0 bottom-0 items-center flex justify-center"> <ChevronRightIcon /> </div> </DropdownMenuRadix.SubTrigger> ); } function DropdownMenuSubContent({ className, ...props }: React.ComponentProps<typeof DropdownMenuRadix.SubContent>) { return ( <DropdownMenuRadix.SubContent data-slot="dropdown-menu-sub-content" className={cn( className, "z-50 origin-(--radix-dropdown-menu-content-transform-origin) bg-gray-1 border border-gray-a6 rounded-sm relative shadow-md data-[state=open]:animate-popover-show data-[state=closed]:animate-popover-hide" )} {...props} /> ); } export { DropdownMenu, DropdownMenuPortal, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuGroup, DropdownMenuLabel, DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubTrigger, DropdownMenuSubContent, }; ``` </Step> <Step> Copy and paste the use mobile hook into your `hooks/use-mobile.ts` file. ```ts import * as React from "react" const MOBILE_BREAKPOINT = 768 export function useIsMobile(breakpoint = MOBILE_BREAKPOINT) { const [isMobile, setIsMobile] = React.useState<boolean | undefined>(undefined) React.useEffect(() => { const mql = window.matchMedia(`(max-width: ${breakpoint - 1}px)`) const onChange = () => { setIsMobile(window.innerWidth < breakpoint) } mql.addEventListener("change", onChange) setIsMobile(window.innerWidth < breakpoint) return () => mql.removeEventListener("change", onChange) }, [breakpoint]) return !!isMobile } ``` </Step> <Step> Copy and paste the ResponsiveDropdownMenu component into your `components/ui/ResponsiveDropdownMenu.tsx` file. ```tsx "use client"; /** * @description A dropdown menu on desktop and a stacked drawer on mobile. / import as React from "react"; import { createPortal } from "react-dom"; import { Slot } from "@radix-ui/react-slot"; import { CheckIcon, ChevronLeftIcon, ChevronRightIcon, DotFilledIcon, } from "@radix-ui/react-icons"; import { cn } from "@/utils/class-names"; import { useIsMobile } from "@/hooks/use-mobile"; import { Drawer, DrawerContent, DrawerHeader, DrawerTitle, DrawerTrigger, } from "@/components/ui/Drawer"; import { DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, } from "@/components/ui/DropdownMenu"; type StackEntry = { id: string; title: React.ReactNode; }; type ResponsiveDropdownMenuContextValue = { isMobile: boolean; open: boolean; setOpen: (open: boolean) => void; stack: StackEntry[]; push: (entry: StackEntry) => void; pop: () => void; portalContainer: HTMLDivElement | null; setPortalContainer: (container: HTMLDivElement | null) => void; }; const ResponsiveDropdownMenuContext = React.createContext<ResponsiveDropdownMenuContextValue | null>(null); const MobilePanelDepthContext = React.createContext(0); const SubContext = React.createContext<{ id: string; depth: number } | null>( null, ); const RadioGroupContext = React.createContext<{ value?: string; onValueChange?: (value: string) => void; } | null>(null); function useResponsiveDropdownMenu() { const context = React.useContext(ResponsiveDropdownMenuContext); if (!context) { throw new Error( "`useResponsiveDropdownMenu` must be used within `ResponsiveDropdownMenu`", ); } return context; } interface ResponsiveDropdownMenuProps extends React.ComponentProps<typeof DropdownMenu> { breakpoint?: number; } function ResponsiveDropdownMenu({ breakpoint = 768, open: openProp, defaultOpen = false, onOpenChange, children, modal, ...props }: ResponsiveDropdownMenuProps) { const isMobile = useIsMobile(breakpoint); const [internalOpen, setInternalOpen] = React.useState(defaultOpen); const [stack, setStack] = React.useState<StackEntry[]>([]); const [portalContainer, setPortalContainer] = React.useState<HTMLDivElement | null>(null); const open = openProp ?? internalOpen; const setOpen = React.useCallback( (nextOpen: boolean) => { if (openProp === undefined) setInternalOpen(nextOpen); if (!nextOpen) setStack([]); onOpenChange?.(nextOpen); }, [onOpenChange, openProp], ); const push = React.useCallback((entry: StackEntry) => { setStack((current) => { const existingIndex = current.findIndex(({ id }) => id === entry.id); if (existingIndex >= 0) return current.slice(0, existingIndex + 1); return [...current, entry]; }); }, []); const pop = React.useCallback(() => { setStack((current) => current.slice(0, -1)); }, []); const context = React.useMemo( () => ({ isMobile, open, setOpen, stack, push, pop, portalContainer, setPortalContainer, }), [isMobile, open, pop, portalContainer, push, setOpen, stack], ); const root = isMobile ? ( <Drawer open={open} onOpenChange={setOpen} modal={modal}> {children} </Drawer> ) : ( <DropdownMenu open={open} onOpenChange={setOpen} modal={modal} {...props}> {children} </DropdownMenu> ); return ( <ResponsiveDropdownMenuContext.Provider value={context}> {root} </ResponsiveDropdownMenuContext.Provider> ); } function ResponsiveDropdownMenuTrigger({ ...props }: React.ComponentProps<typeof DropdownMenuTrigger>) { const { isMobile } = useResponsiveDropdownMenu(); if (isMobile) { return <DrawerTrigger data-variant="drawer" {...props} />; } return <DropdownMenuTrigger data-variant="dropdown" {...props} />; } function ResponsiveDropdownMenuPortal({ children, ...props }: React.ComponentProps<typeof DropdownMenuPortal>) { const { isMobile } = useResponsiveDropdownMenu(); if (isMobile) return <>{children}</>; return <DropdownMenuPortal {...props}>{children}</DropdownMenuPortal>; } interface ResponsiveDropdownMenuContentProps extends React.ComponentProps<typeof DropdownMenuContent> { mobileTitle?: React.ReactNode; } function ResponsiveDropdownMenuContent({ className, children, mobileTitle = "Menu", ...props }: ResponsiveDropdownMenuContentProps) { const { isMobile, stack, pop, setPortalContainer } = useResponsiveDropdownMenu(); if (!isMobile) { return ( <DropdownMenuContent data-variant="dropdown" className={className} {...props} > {children} </DropdownMenuContent> ); } const currentTitle = stack[stack.length - 1]?.title ?? mobileTitle; return ( <DrawerContent data-variant="drawer" className={cn("responsive-dropdown-drawer", className)} > <DrawerHeader className="responsive-dropdown-header"> {stack.length > 0 ? ( <button type="button" className="responsive-dropdown-back" onClick={pop} aria-label="Back" > <ChevronLeftIcon className="icon" /> </button> ) : null} <DrawerTitle className="responsive-dropdown-title"> {currentTitle} </DrawerTitle> </DrawerHeader> <div ref={setPortalContainer} className="responsive-dropdown-stack" data-depth={stack.length} > <MobilePanelDepthContext.Provider value={0}> <div className="responsive-dropdown-panel" data-panel-state={stack.length === 0 ? "current" : "previous"} aria-hidden={stack.length > 0} > {children} </div> </MobilePanelDepthContext.Provider> </div> </DrawerContent> ); } function ResponsiveDropdownMenuGroup({ className, ...props }: React.ComponentProps<typeof DropdownMenuGroup>) { const { isMobile } = useResponsiveDropdownMenu(); if (isMobile) { return ( <div role="group" data-slot="responsive-dropdown-menu-group" className={className} {...props} /> ); } return <DropdownMenuGroup className={className} {...props} />; } function ResponsiveDropdownMenuItem({ asChild, children, className, disabled, onClick, onSelect, ...props }: React.ComponentProps<typeof DropdownMenuItem>) { const { isMobile, setOpen } = useResponsiveDropdownMenu(); if (!isMobile) { return ( <DropdownMenuItem asChild={asChild} className={className} disabled={disabled} onClick={onClick} onSelect={onSelect} {...props} > {children} </DropdownMenuItem> ); } const Comp = asChild ? Slot : "button"; return ( <Comp {...(props as React.ComponentPropsWithoutRef<"button">)} type={asChild ? undefined : "button"} role="menuitem" disabled={asChild ? undefined : disabled} data-disabled={disabled ? "" : undefined} className={cn("responsive-dropdown-item", className)} onClick={(event) => { onClick?.(event as never); onSelect?.(event.nativeEvent); if (!event.defaultPrevented && !disabled) setOpen(false); }} > {children} </Comp> ); } function ResponsiveDropdownMenuCheckboxItem({ checked, children, className, disabled, onCheckedChange, onSelect, ...props }: React.ComponentProps<typeof DropdownMenuCheckboxItem>) { const { isMobile } = useResponsiveDropdownMenu(); if (!isMobile) { return ( <DropdownMenuCheckboxItem checked={checked} className={className} disabled={disabled} onCheckedChange={onCheckedChange} onSelect={onSelect} {...props} > {children} </DropdownMenuCheckboxItem> ); } const isChecked = checked === true; return ( <button {...(props as React.ComponentPropsWithoutRef<"button">)} type="button" role="menuitemcheckbox" aria-checked={isChecked} disabled={disabled} className={cn("responsive-dropdown-item", className)} onClick={(event) => { onSelect?.(event.nativeEvent); if (!event.defaultPrevented && !disabled) { onCheckedChange?.(!isChecked); } }} > <span className="responsive-dropdown-indicator" aria-hidden="true"> {isChecked ? <CheckIcon className="icon" /> : null} </span> {children} </button> ); } function ResponsiveDropdownMenuRadioGroup({ value, onValueChange, children, className, ...props }: React.ComponentProps<typeof DropdownMenuRadioGroup>) { const { isMobile } = useResponsiveDropdownMenu(); if (!isMobile) { return ( <DropdownMenuRadioGroup value={value} onValueChange={onValueChange} className={className} {...props} > {children} </DropdownMenuRadioGroup> ); } return ( <RadioGroupContext.Provider value={{ value, onValueChange }}> <div role="group" className={className} {...(props as React.ComponentPropsWithoutRef<"div">)} > {children} </div> </RadioGroupContext.Provider> ); } function ResponsiveDropdownMenuRadioItem({ value, children, className, disabled, onSelect, ...props }: React.ComponentProps<typeof DropdownMenuRadioItem>) { const { isMobile } = useResponsiveDropdownMenu(); const group = React.useContext(RadioGroupContext); if (!isMobile) { return ( <DropdownMenuRadioItem value={value} className={className} disabled={disabled} onSelect={onSelect} {...props} > {children} </DropdownMenuRadioItem> ); } const isChecked = group?.value === value; return ( <button {...(props as React.ComponentPropsWithoutRef<"button">)} type="button" role="menuitemradio" aria-checked={isChecked} disabled={disabled} className={cn("responsive-dropdown-item", className)} onClick={(event) => { onSelect?.(event.nativeEvent); if (!event.defaultPrevented && !disabled) group?.onValueChange?.(value); }} > <span className="responsive-dropdown-indicator" aria-hidden="true"> {isChecked ? <DotFilledIcon className="icon" /> : null} </span> {children} </button> ); } function ResponsiveDropdownMenuLabel({ className, ...props }: React.ComponentProps<typeof DropdownMenuLabel>) { const { isMobile } = useResponsiveDropdownMenu(); if (isMobile) { return ( <div data-slot="responsive-dropdown-menu-label" className={cn("responsive-dropdown-label", className)} {...props} /> ); } return <DropdownMenuLabel className={className} {...props} />; } function ResponsiveDropdownMenuSeparator({ className, ...props }: React.ComponentProps<typeof DropdownMenuSeparator>) { const { isMobile } = useResponsiveDropdownMenu(); if (isMobile) { return ( <div role="separator" className={cn("responsive-dropdown-separator", className)} {...props} /> ); } return <DropdownMenuSeparator className={className} {...props} />; } function ResponsiveDropdownMenuShortcut({ className, ...props }: React.ComponentProps<typeof DropdownMenuShortcut>) { const { isMobile } = useResponsiveDropdownMenu(); return ( <DropdownMenuShortcut aria-hidden={isMobile || undefined} className={cn(isMobile && "responsive-dropdown-shortcut", className)} {...props} /> ); } function ResponsiveDropdownMenuSub({ children, ...props }: React.ComponentProps<typeof DropdownMenuSub>) { const { isMobile } = useResponsiveDropdownMenu(); const parentDepth = React.useContext(MobilePanelDepthContext); const id = React.useId(); if (!isMobile) { return <DropdownMenuSub {...props}>{children}</DropdownMenuSub>; } return ( <SubContext.Provider value={{ id, depth: parentDepth + 1 }}> {children} </SubContext.Provider> ); } function ResponsiveDropdownMenuSubTrigger({ asChild, children, className, disabled, ...props }: React.ComponentProps<typeof DropdownMenuSubTrigger>) { const { isMobile, push } = useResponsiveDropdownMenu(); const sub = React.useContext(SubContext); if (!isMobile) { return ( <DropdownMenuSubTrigger className={className} disabled={disabled} {...props} > {children} </DropdownMenuSubTrigger> ); } if (!sub) { throw new Error( "`ResponsiveDropdownMenuSubTrigger` must be used within `ResponsiveDropdownMenuSub`", ); } const title = React.isValidElement<{ children?: React.ReactNode }>(children) ? children.props.children : children; if (asChild && React.isValidElement<{ children?: React.ReactNode }>(children)) { return ( <Slot {...(props as React.ComponentPropsWithoutRef<typeof Slot>)} role="menuitem" data-disabled={disabled ? "" : undefined} className={cn("responsive-dropdown-item", className)} onClick={() => { if (!disabled) push({ id: sub.id, title }); }} > {React.cloneElement( children, undefined, <> {children.props.children} <ChevronRightIcon className="icon responsive-dropdown-chevron" /> </> )} </Slot> ); } return ( <button {...(props as React.ComponentPropsWithoutRef<"button">)} type="button" role="menuitem" disabled={disabled} data-disabled={disabled ? "" : undefined} className={cn("responsive-dropdown-item", className)} onClick={() => push({ id: sub.id, title })} > {children} <ChevronRightIcon className="icon responsive-dropdown-chevron" /> </button> ); } function ResponsiveDropdownMenuSubContent({ children, className, ...props }: React.ComponentProps<typeof DropdownMenuSubContent>) { const { isMobile, portalContainer, stack } = useResponsiveDropdownMenu(); const sub = React.useContext(SubContext); if (!isMobile) { return ( <DropdownMenuSubContent className={className} {...props}> {children} </DropdownMenuSubContent> ); } if (!sub || !portalContainer) return null; const stackIndex = stack.findIndex(({ id }) => id === sub.id); const panelState = stackIndex === -1 ? "next" : stackIndex === stack.length - 1 ? "current" : "previous"; return createPortal( <MobilePanelDepthContext.Provider value={sub.depth}> <div role="menu" className={cn("responsive-dropdown-panel", className)} data-panel-state={panelState} aria-hidden={panelState !== "current"} {...(props as React.ComponentPropsWithoutRef<"div">)} > {children} </div> </MobilePanelDepthContext.Provider>, portalContainer, ); } export { ResponsiveDropdownMenu, ResponsiveDropdownMenuCheckboxItem, ResponsiveDropdownMenuContent, ResponsiveDropdownMenuGroup, ResponsiveDropdownMenuItem, ResponsiveDropdownMenuLabel, ResponsiveDropdownMenuPortal, ResponsiveDropdownMenuRadioGroup, ResponsiveDropdownMenuRadioItem, ResponsiveDropdownMenuSeparator, ResponsiveDropdownMenuShortcut, ResponsiveDropdownMenuSub, ResponsiveDropdownMenuSubContent, ResponsiveDropdownMenuSubTrigger, ResponsiveDropdownMenuTrigger, }; ``` </Step> </Steps> ## Usage [#usage] ### CustomBreakpoint [#custombreakpoint] ```tsx export const CustomBreakpoint = () => ( <ResponsiveDropdownMenu breakpoint={1024}> <ResponsiveDropdownMenuTrigger asChild> <Button variant="menu">Breakpoint 1024</Button> </ResponsiveDropdownMenuTrigger> <ResponsiveDropdownMenuContent mobileTitle="Project actions"> <ResponsiveDropdownMenuItem>Rename</ResponsiveDropdownMenuItem> <ResponsiveDropdownMenuItem>Duplicate</ResponsiveDropdownMenuItem> <ResponsiveDropdownMenuItem>Archive</ResponsiveDropdownMenuItem> </ResponsiveDropdownMenuContent> </ResponsiveDropdownMenu> ) ``` # Scroll Area (/docs/components/scroll-area) ## Preview [#preview] <ComponentPreview name="scroll-area-demo" description="Augments native scroll functionality for custom cross-browser styling."> ```tsx import * as React from "react"; import { ScrollArea } from "@/components/ui/ScrollArea"; export function ScrollAreaDemo() { return ( <ScrollArea className="h-[70dvh] w-48 rounded-md border border-gray-6"> <div className="p-2"> <h4 className="mb-2 text-sm font-medium leading-none">Tags</h4> {tags.map((tag) => ( <React.Fragment key={tag}> <div className="text-sm">{tag}</div> <div className="my-1 h-px bg-gray-6" /> </React.Fragment> ))} </div> </ScrollArea> ) ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/scroll-area ``` ### Manual [#manual] <Steps> <Step> Install the following dependencies: ```bash pnpm install radix-ui ``` </Step> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the ScrollArea component into your `components/ui/ScrollArea.tsx` file. ```tsx "use client" /** * @description Augments native scroll functionality for custom cross-browser styling. / import as React from "react" import { ScrollArea as ScrollAreaPrimitive } from "radix-ui" import { cn } from "@/utils/class-names" const ScrollViewport = ScrollAreaPrimitive.Viewport; const ScrollArea = React.forwardRef< React.ElementRef<typeof ScrollAreaPrimitive.Root>, React.ComponentPropsWithoutRef<typeof ScrollAreaPrimitive.Root> >(({ className, children, ...props }, ref) => ( <ScrollAreaPrimitive.Root ref={ref} className={cn("relative overflow-hidden cursor-default", className)} {...props} > <ScrollAreaPrimitive.Viewport className="h-full w-full rounded-[inherit]"> {children} </ScrollAreaPrimitive.Viewport> <ScrollBar /> <ScrollAreaPrimitive.Corner /> </ScrollAreaPrimitive.Root> )) ScrollArea.displayName = ScrollAreaPrimitive.Root.displayName const ScrollBar = React.forwardRef< React.ElementRef<typeof ScrollAreaPrimitive.ScrollAreaScrollbar>, React.ComponentPropsWithoutRef<typeof ScrollAreaPrimitive.ScrollAreaScrollbar> >(({ className, orientation = "vertical", ...props }, ref) => ( <ScrollAreaPrimitive.ScrollAreaScrollbar ref={ref} orientation={orientation} className={cn( "flex touch-none select-none transition-colors cursor-default bg-gray-a2", orientation === "vertical" && "h-full w-0.5 border-l border-l-transparent p-[1px]", orientation === "horizontal" && "h-0.5 flex-col border-t border-t-transparent p-[1px]", className )} {...props} > <ScrollAreaPrimitive.ScrollAreaThumb className="relative flex-1 rounded-full bg-gray-6 cursor-grab active:cursor-grabbing" /> </ScrollAreaPrimitive.ScrollAreaScrollbar> )) ScrollBar.displayName = ScrollAreaPrimitive.ScrollAreaScrollbar.displayName export { ScrollArea, ScrollBar, ScrollViewport } ``` </Step> </Steps> # Scroll Spy (/docs/components/scroll-spy) ## Preview [#preview] <ComponentPreview name="scroll-spy-demo" description="A list of links that marks the section in view."> ```tsx import { ScrollSpy } from "@/components/ui/ScrollSpy"; export function ScrollSpyDemo() { return ( <div className="flex items-start gap-1"> <ScrollSpy items={[ { id: "spy-overview", label: "Overview" }, { id: "spy-color", label: "Color" }, { id: "spy-type", label: "Type" }, ]} /> <div className="flex min-w-0 flex-1 flex-col gap-1"> <section id="spy-overview" className="h-16 rounded-sm bg-gray-3 p-1"> Overview </section> <section id="spy-color" className="h-16 rounded-sm bg-accent-3 p-1"> Color </section> <section id="spy-type" className="h-16 rounded-sm bg-gray-3 p-1"> Type </section> </div> </div> ) ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/scroll-spy ``` ### Manual [#manual] <Steps> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the ScrollSpy component into your `components/ui/ScrollSpy.tsx` file. ```tsx "use client"; import * as React from "react"; import { cn } from "@/utils/class-names"; type ScrollSpyItem = { id: string; label: string }; function ScrollSpy({ className, items, label = "On this page", }: { className?: string; items: ScrollSpyItem[]; label?: string; }) { const [active, setActive] = React.useState(items[0]?.id); const signature = items.map((item) => item.id).join("|"); React.useEffect(() => { const nodes = signature .split("|") .filter(Boolean) .map((id) => document.getElementById(id)) .filter((node): node is HTMLElement => Boolean(node)); if (!nodes.length) return; const observer = new IntersectionObserver( (entries) => { const visible = entries .filter((entry) => entry.isIntersecting) .sort((a, b) => b.intersectionRatio - a.intersectionRatio)[0]; if (visible?.target.id) setActive(visible.target.id); }, { rootMargin: "-20% 0px -60% 0px" }, ); nodes.forEach((node) => observer.observe(node)); return () => observer.disconnect(); }, [signature]); return ( <nav aria-label={label} data-slot="scroll-spy" className={cn("flex flex-col gap-0.5", className)}> {items.map((item) => ( <a key={item.id} href={`#${item.id}`} aria-current={active === item.id ? "true" : undefined} className="rounded-sm px-1 py-0.5 text-gray-11 hover:bg-gray-3 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent-8 aria-[current=true]:bg-accent-3 aria-[current=true]:text-accent-11" > {item.label} </a> ))} </nav> ); } export { ScrollSpy }; export type { ScrollSpyItem }; ``` </Step> </Steps> # Scroller (/docs/components/scroller) ## Preview [#preview] <ComponentPreview name="scroller-demo" description="A horizontal strip with back and forward controls."> ```tsx import { Scroller } from "@/components/ui/Scroller"; export function ScrollerDemo() { return ( <Scroller> {pages.map((page) => ( <div key={page} className="flex h-8 w-12 shrink-0 items-center justify-center rounded-sm bg-accent-3" > {page} </div> ))} </Scroller> ) ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/scroller ``` ### Manual [#manual] <Steps> <Step> Install the following dependencies: ```bash pnpm install @radix-ui/react-icons ``` </Step> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the Scroller component into your `components/ui/Scroller.tsx` file. ```tsx "use client"; import * as React from "react"; import { ChevronLeftIcon, ChevronRightIcon } from "@radix-ui/react-icons"; import { cn } from "@/utils/class-names"; function Scroller({ className, label = "Scroller", children, }: { className?: string; label?: string; children: React.ReactNode; }) { const ref = React.useRef<HTMLDivElement>(null); const move = (direction: number) => { const root = ref.current; if (!root) return; const reduced = window.matchMedia("(prefers-reduced-motion: reduce)").matches; root.scrollBy({ left: direction * root.clientWidth * 0.8, behavior: reduced ? "auto" : "smooth" }); }; return ( <div data-slot="scroller" className={cn("flex items-center gap-0.5", className)}> <button type="button" aria-label="Scroll back" className="inline-flex size-3 items-center justify-center rounded-sm border border-gray-6 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent-8" onClick={() => move(-1)} > <ChevronLeftIcon className="icon" /> </button> <div ref={ref} role="region" aria-label={label} tabIndex={0} className="flex gap-0.5 overflow-x-auto" onKeyDown={(event) => { if (event.key === "ArrowRight") move(1); if (event.key === "ArrowLeft") move(-1); }} > {children} </div> <button type="button" aria-label="Scroll forward" className="inline-flex size-3 items-center justify-center rounded-sm border border-gray-6 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent-8" onClick={() => move(1)} > <ChevronRightIcon className="icon" /> </button> </div> ); } export { Scroller }; ``` </Step> </Steps> # Search (/docs/components/search) ## Preview [#preview] <ComponentPreview name="search-demo" description="A search bar that expands into a results view."> ```tsx import { Search } from "@/components/ui/Search"; export function SearchDemo() { return <Search items={items} placeholder="Search foundations" defaultExpanded />; } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/search ``` ### Manual [#manual] <Steps> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the command component into your `components/ui/Command.tsx` file. ```tsx "use client"; import { Dialog as CommandDialogPrimitive } from "@base-ui/react/dialog"; import { MagnifyingGlassIcon } from "@radix-ui/react-icons"; import * as React from "react"; import { cn } from "@/utils/class-names"; import { Autocomplete, AutocompleteCollection, AutocompleteEmpty, AutocompleteGroup, AutocompleteGroupLabel, AutocompleteInput, AutocompleteItem, AutocompleteList, AutocompleteSeparator, } from "@/components/ui/Autocomplete"; const CommandInputContext = React.createContext<{ inputRef: React.RefObject<HTMLInputElement | null> | null; }>({ inputRef: null, }); const CommandDialog = CommandDialogPrimitive.Root; const CommandDialogPortal = CommandDialogPrimitive.Portal; function CommandDialogTrigger(props: CommandDialogPrimitive.Trigger.Props) { return ( <CommandDialogPrimitive.Trigger data-slot="command-dialog-trigger" {...props} /> ); } function CommandDialogBackdrop({ className, ...props }: CommandDialogPrimitive.Backdrop.Props) { return ( <CommandDialogPrimitive.Backdrop className={cn( "aura-overlay z-50", className, )} data-slot="command-dialog-backdrop" {...props} /> ); } function CommandDialogViewport({ className, ...props }: CommandDialogPrimitive.Viewport.Props) { return ( <CommandDialogPrimitive.Viewport className={cn( "fixed inset-0 z-50 flex flex-col items-center px-2 py-[max(--spacing(4),4vh)] sm:py-[10vh]", className, )} data-slot="command-dialog-viewport" {...props} /> ); } function CommandDialogPopup({ className, children, ...props }: CommandDialogPrimitive.Popup.Props) { const inputRef = React.useRef<HTMLInputElement>(null); return ( <CommandDialogPortal> <CommandDialogBackdrop /> <CommandDialogViewport> <CommandDialogPrimitive.Popup className={cn( "relative row-start-2 flex max-h-100 min-h-0 w-full min-w-0 max-w-xl flex-col rounded-2xl border border-gray-a6 bg-gray-1 bg-clip-padding text-gray-12 shadow-lg before:pointer-events-none before:absolute before:inset-0 before:rounded-[calc(var(--radius-2xl)-1px)] before:bg-gray-a2 data-nested-dialog-open:origin-top :data-[slot=scroll-area-viewport]:data-has-overflow-y:pe-1", className, )} data-slot="command-dialog-popup" initialFocus={inputRef} {...props} > <CommandInputContext.Provider value={{ inputRef }}> {children} </CommandInputContext.Provider> </CommandDialogPrimitive.Popup> </CommandDialogViewport> </CommandDialogPortal> ); } function Command({ autoHighlight = "always", keepHighlight = true, open = true, ...props }: React.ComponentProps<typeof Autocomplete>) { return ( <Autocomplete autoHighlight={autoHighlight} keepHighlight={keepHighlight} open={open} {...props} /> ); } function CommandInput({ className, placeholder = undefined, ...props }: React.ComponentProps<typeof AutocompleteInput>) { const { inputRef } = React.useContext(CommandInputContext); return ( <div className="px-1.5 py-0.5"> <AutocompleteInput className={cn( "border-transparent! bg-transparent shadow-none before:hidden has-focus-visible:ring-0 pl-5", className, )} placeholder={placeholder} ref={inputRef} size="lg" startAddon={<MagnifyingGlassIcon />} {...props} /> </div> ); } function CommandList({ className, ...props }: React.ComponentProps<typeof AutocompleteList>) { return ( <AutocompleteList className={cn("not-empty:scroll-py-2 not-empty:p-2", className)} data-slot="command-list" {...props} /> ); } function CommandEmpty({ className, ...props }: React.ComponentProps<typeof AutocompleteEmpty>) { return ( <AutocompleteEmpty className={cn("empty:hidden not-empty:py-6", className)} data-slot="command-empty" {...props} /> ); } function CommandPanel({ className, ...props }: React.ComponentProps<"div">) { return ( <div className="-mx-px relative min-h-0 rounded-t-xl border border-gray-a6 bg-gray-1 bg-clip-padding [clip-path:inset(0_1px)] before:pointer-events-none before:absolute before:inset-0 before:rounded-t-[calc(var(--radius-xl)-1px)] :data-[slot=scroll-area-scrollbar]:mt-2" {...props} /> ); } function CommandGroup({ className, ...props }: React.ComponentProps<typeof AutocompleteGroup>) { return ( <AutocompleteGroup className={className} data-slot="command-group" {...props} /> ); } function CommandGroupLabel({ className, ...props }: React.ComponentProps<typeof AutocompleteGroupLabel>) { return ( <AutocompleteGroupLabel className={className} data-slot="command-group-label" {...props} /> ); } function CommandCollection({ ...props }: React.ComponentProps<typeof AutocompleteCollection>) { return <AutocompleteCollection data-slot="command-collection" {...props} />; } function CommandItem({ className, ...props }: React.ComponentProps<typeof AutocompleteItem>) { return ( <AutocompleteItem className={cn("py-1.5", className)} data-slot="command-item" {...props} /> ); } function CommandSeparator({ className, ...props }: React.ComponentProps<typeof AutocompleteSeparator>) { return ( <AutocompleteSeparator className={cn("my-2", className)} data-slot="command-separator" {...props} /> ); } function CommandShortcut({ className, ...props }: React.ComponentProps<"kbd">) { return ( <span className={cn( "ms-auto font-medium text-gray-11 text-xs tracking-widest", className, )} data-slot="command-shortcut" {...props} /> ); } function CommandFooter({ className, ...props }: React.ComponentProps<"div">) { return ( <div className={cn( "flex items-center justify-between gap-1 rounded-b-[calc(var(--radius-2xl)-1px)] border-t border-gray-a6 bg-gray-2 px-2 py-1 text-gray-11 text-xs z-10", className, )} data-slot="command-footer" {...props} /> ); } export { Command, CommandCollection, CommandDialog, CommandDialogPopup, CommandDialogTrigger, CommandEmpty, CommandFooter, CommandGroup, CommandGroupLabel, CommandInput, CommandItem, CommandList, CommandPanel, CommandSeparator, CommandShortcut, }; ``` </Step> <Step> Copy and paste the Search component into your `components/ui/Search.tsx` file. ```tsx "use client"; import * as React from "react"; import { cn } from "@/utils/class-names"; import { Command, CommandCollection, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandPanel, } from "@/components/ui/Command"; type SearchItem = { value: string; label: string; }; function Search({ className, items, placeholder = "Search", label = "Search", empty = "No results.", defaultExpanded = false, }: { className?: string; items: SearchItem[]; placeholder?: string; label?: string; empty?: string; defaultExpanded?: boolean; }) { const [expanded, setExpanded] = React.useState(defaultExpanded); return ( <div data-slot="search" data-expanded={expanded ? "true" : "false"} className={cn("w-full max-w-xl rounded-sm border border-gray-6 bg-gray-1", className)} > <Command items={[{ value: "Results", items }]} open={expanded} onOpenChange={setExpanded}> <CommandInput aria-label={label} placeholder={placeholder} onFocus={() => setExpanded(true)} onKeyDown={(event) => { if (event.key === "Escape") setExpanded(false); }} /> {expanded ? ( <CommandPanel> <CommandEmpty>{empty}</CommandEmpty> <CommandList> {(group: { value: string; items: SearchItem[] }) => ( <CommandGroup key={group.value} items={group.items}> <CommandCollection> {(item: SearchItem) => ( <CommandItem key={item.value} value={item.value} onClick={() => setExpanded(false)} > {item.label} </CommandItem> )} </CommandCollection> </CommandGroup> )} </CommandList> </CommandPanel> ) : null} </Command> </div> ); } export { Search }; export type { SearchItem }; ``` </Step> </Steps> # Section (/docs/components/section) ## Preview [#preview] <ComponentPreview name="section-demo" description="A semantic section container with configurable layout variants."> ```tsx import { AuraContainer, Section, } from "@/components/ui/Section"; export function SectionDemo() { return ( <Section> <h1>Section Title</h1> <p> This is a default section with some content. Sections help organize and structure your content with consistent spacing and layout. </p> </Section> ); } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/section ``` ### Manual [#manual] <Steps> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the Section component into your `components/ui/Section.tsx` file. ```tsx /** * @description A semantic section container with configurable layout variants. / import as React from "react"; import { cn } from "@/utils/class-names"; export type AuraContainer = "smash" | "smesh" | "smish" | "smosh" | "smush"; function Wrapper({ className, ...props }: React.ComponentProps<"div">) { return ( <section className={cn("pad", className)} data-slot="wrapper" {...props} /> ); } function WrapperContainer({ container = "smush", className, ...props }: React.ComponentProps<"div"> & { container?: AuraContainer; className?: string; }) { return ( <div data-slot="wrapper-container" className={cn(container, className)} {...props} /> ); } type SectionProps = { children: React.ReactNode; container?: React.ComponentProps<typeof WrapperContainer>["container"]; subClassName?: string; } & React.ComponentProps<typeof Wrapper>; const Section = ({ children, container, subClassName, ...props }: SectionProps) => { return ( <Wrapper {...props}> <WrapperContainer container={container} className={subClassName}> {children} </WrapperContainer> </Wrapper> ); }; export { Wrapper, WrapperContainer, Section }; ``` </Step> </Steps> # Segmented Input (/docs/components/segmented-input) ## Preview [#preview] <ComponentPreview name="segmented-input-demo" description="A group of connected input fields that appear as a single segmented visual unit."> ```tsx import * as React from "react"; import { Button } from "@/components/ui/Button"; import { SegmentedInput, SegmentedInputItem, } from "@/components/ui/SegmentedInput"; export function SegmentedInputDemo() { const [values, setValues] = React.useState({ first: "", second: "", third: "", }); const onValueChange = React.useCallback( (field: keyof typeof values) => (event: React.ChangeEvent<HTMLInputElement>) => { setValues((prev) => ({ ...prev, [field]: event.target.value, })); }, [], ); return ( <div className="flex w-full max-w-sm flex-col gap-1"> <label className="text-sm font-medium text-gray-12"> Enter your details </label> <SegmentedInput className="w-full" aria-label="Name segments"> <SegmentedInputItem placeholder="First" value={values.first} onChange={onValueChange("first")} aria-label="First name" /> <SegmentedInputItem placeholder="Second" value={values.second} onChange={onValueChange("second")} aria-label="Middle name" /> <SegmentedInputItem placeholder="Third" value={values.third} onChange={onValueChange("third")} aria-label="Last name" /> </SegmentedInput> </div> ); } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/segmented-input ``` ### Manual [#manual] <Steps> <Step> Install the following dependencies: ```bash pnpm install class-variance-authority radix-ui ``` </Step> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the input component into your `components/ui/Input.tsx` file. ```tsx /** * @description Displays a form input field or a component that looks like an input field. / import as React from "react"; import { cn } from "@/utils/class-names"; /** * Matches Button sm, md, and lg (`h-3`, `h-4`, `h-5`). * Vertical padding is 0 so the spacing height is the border box, same as Button. */ const inputSizeClassName = { sm: "box-border h-3 px-2 py-0", default: "box-border h-4 px-2 py-0", lg: "box-border h-5 px-2 py-0", } as const; type InputSize = keyof typeof inputSizeClassName; function Input({ className, size = "default", ...props }: Omit<React.ComponentProps<"input">, "size"> & { size?: InputSize; }) { return ( <input data-slot="input" data-size={size} className={cn(inputSizeClassName[size], className)} {...props} /> ); } export { Input }; export type { InputSize }; ``` </Step> <Step> Copy and paste the SegmentedInput component into your `components/ui/SegmentedInput.tsx` file. ```tsx "use client"; /** * @description A group of connected input fields that appear as a single segmented visual unit. / import as React from "react"; import { cva, type VariantProps } from "class-variance-authority"; import { Direction as DirectionPrimitive, Slot as SlotPrimitive, } from "radix-ui"; import { cn } from "@/utils/class-names"; import { Input } from "@/components/ui/Input"; const ROOT_NAME = "SegmentedInput"; const ITEM_NAME = "SegmentedInputItem"; type Direction = "ltr" | "rtl"; type Orientation = "horizontal" | "vertical"; type Size = "default" | "sm" | "lg"; type Position = "isolated" | "first" | "middle" | "last"; interface SegmentedInputContextValue { dir?: Direction; orientation?: Orientation; size?: Size; disabled?: boolean; invalid?: boolean; required?: boolean; } const SegmentedInputContext = React.createContext<SegmentedInputContextValue | null>(null); function useSegmentedInputContext(consumerName: string) { const context = React.useContext(SegmentedInputContext); if (!context) { throw new Error(`\`${consumerName}\` must be used within \`${ROOT_NAME}\``); } return context; } interface SegmentedInputProps extends React.ComponentProps<"div"> { dir?: Direction; orientation?: Orientation; size?: Size; asChild?: boolean; disabled?: boolean; invalid?: boolean; required?: boolean; } function SegmentedInput(props: SegmentedInputProps) { const { size = "default", dir: dirProp, orientation = "horizontal", children, className, asChild, disabled, invalid, required, ...rootProps } = props; const dir = DirectionPrimitive.useDirection(dirProp); const contextValue = React.useMemo<SegmentedInputContextValue>( () => ({ dir, orientation, size, disabled, invalid, required, }), [dir, orientation, size, disabled, invalid, required], ); const childrenArray = React.Children.toArray(children); const childrenCount = childrenArray.length; const segmentedInputItems = React.Children.map(children, (child, index) => { if (React.isValidElement<SegmentedInputItemProps>(child)) { if (!child.props.position) { let position: Position; if (childrenCount === 1) { position = "isolated"; } else if (index === 0) { position = "first"; } else if (index === childrenCount - 1) { position = "last"; } else { position = "middle"; } return React.cloneElement(child, { position }); } } return child; }); const RootPrimitive = asChild ? SlotPrimitive.Slot : "div"; return ( <SegmentedInputContext.Provider value={contextValue}> <RootPrimitive role="group" aria-orientation={orientation} data-slot="segmented-input" data-orientation={orientation} data-disabled={disabled ? "" : undefined} data-invalid={invalid ? "" : undefined} data-required={required ? "" : undefined} dir={dir} {...rootProps} className={cn( "flex", orientation === "horizontal" ? "flex-row" : "flex-col", className, )} > {segmentedInputItems} </RootPrimitive> </SegmentedInputContext.Provider> ); } const segmentedInputItemVariants = cva( [ "relative min-w-0 flex-1 rounded-md border border-gray-7 bg-gray-1 text-gray-12 transition-colors outline-none", "selection:bg-accent-4 selection:text-gray-12 placeholder:text-gray-11", "focus-visible:z-10 focus-visible:border-gray-8 focus-visible:ring-2 focus-visible:ring-gray-8", "disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50", "aria-invalid:border-danger aria-invalid:ring-2 aria-invalid:ring-danger/20", ].join(" "), { variants: { position: { isolated: "", first: "rounded-e-none", middle: "-ms-px rounded-none border-l-0", last: "-ms-px rounded-s-none border-l-0", }, orientation: { horizontal: "", vertical: "", }, size: { // Aura --spacing 13px: avoid text-xs/text-sm on editable inputs (iOS zoom) sm: "h-2.5 px-1", default: "h-3 px-1", lg: "h-4 px-1.5", }, }, compoundVariants: [ { position: "first", orientation: "vertical", class: "ms-0 rounded-e-md rounded-b-none border-l", }, { position: "middle", orientation: "vertical", class: "ms-0 -mt-px rounded-none border-t-0 border-l", }, { position: "last", orientation: "vertical", class: "ms-0 -mt-px rounded-s-md rounded-t-none border-t-0 border-l", }, ], defaultVariants: { position: "isolated", orientation: "horizontal", size: "default", }, }, ); interface SegmentedInputItemProps extends React.ComponentProps<"input">, Omit<VariantProps<typeof segmentedInputItemVariants>, "size"> { asChild?: boolean; } function SegmentedInputItem(props: SegmentedInputItemProps) { const { asChild, className, position, disabled, required, ...inputProps } = props; const context = useSegmentedInputContext(ITEM_NAME); const isDisabled = disabled ?? context.disabled; const isRequired = required ?? context.required; const ItemPrimitive = asChild ? SlotPrimitive.Slot : Input; return ( <ItemPrimitive aria-invalid={context.invalid} aria-required={isRequired} data-disabled={isDisabled ? "" : undefined} data-invalid={context.invalid ? "" : undefined} data-orientation={context.orientation} data-position={position} data-required={isRequired ? "" : undefined} data-slot="segmented-input-item" disabled={isDisabled} required={isRequired} {...inputProps} className={cn( segmentedInputItemVariants({ position, orientation: context.orientation, size: context.size, className, }), )} /> ); } export { SegmentedInput, SegmentedInputItem, SegmentedInput as Root, SegmentedInputItem as Item, segmentedInputItemVariants, type SegmentedInputProps, type SegmentedInputItemProps, }; ``` </Step> </Steps> ## Usage [#usage] ### FormInput [#forminput] ```tsx export const FormInput = () => { const [phoneNumber, setPhoneNumber] = React.useState({ countryCode: "+1", areaCode: "", number: "", }); const onSubmit = React.useCallback( (event: React.FormEvent<HTMLFormElement>) => { event.preventDefault(); }, [], ); return ( <form onSubmit={onSubmit} className="flex w-full max-w-sm flex-col gap-2"> <div className="flex flex-col gap-1"> <label className="text-sm font-medium text-gray-12">Phone Number</label> <SegmentedInput className="w-full" aria-label="Phone number input" > <SegmentedInputItem placeholder="+1" value={phoneNumber.countryCode} onChange={(event) => setPhoneNumber((prev) => ({ ...prev, countryCode: event.target.value, })) } className="w-5 flex-none" aria-label="Country code" /> <SegmentedInputItem placeholder="555" value={phoneNumber.areaCode} onChange={(event) => setPhoneNumber((prev) => ({ ...prev, areaCode: event.target.value, })) } className="w-6 flex-none" maxLength={3} inputMode="numeric" pattern="[0-9]" aria-label="Area code" /> <SegmentedInputItem placeholder="1234567" value={phoneNumber.number} onChange={(event) => setPhoneNumber((prev) => ({ ...prev, number: event.target.value, })) } className="flex-1" maxLength={7} inputMode="numeric" pattern="[0-9]" aria-label="Phone number" /> </SegmentedInput> </div> <Button type="submit" size="sm"> Submit </Button> </form> ); }; ``` ### RgbColor [#rgbcolor] ```tsx export const RgbColor = () => { const [rgb, setRgb] = React.useState({ r: 255, g: 128, b: 0, }); const onChannelChange = React.useCallback( (channel: keyof typeof rgb) => (event: React.ChangeEvent<HTMLInputElement>) => { const value = Number.parseInt(event.target.value, 10); if (!Number.isNaN(value) && value >= 0 && value <= 255) { setRgb((prev) => ({ ...prev, [channel]: value, })); } }, [], ); return ( <div className="flex flex-col gap-1"> <label className="text-sm font-medium text-gray-12">RGB Color</label> <div className="flex items-center gap-1"> <SegmentedInput className="w-fit" aria-label="RGB color input"> <SegmentedInputItem placeholder="255" value={rgb.r} onChange={onChannelChange("r")} className="w-5 flex-none" inputMode="numeric" pattern="[0-9]" min={0} max={255} aria-label="Red channel (0-255)" /> <SegmentedInputItem placeholder="128" value={rgb.g} onChange={onChannelChange("g")} className="w-5 flex-none" inputMode="numeric" pattern="[0-9]" min={0} max={255} aria-label="Green channel (0-255)" /> <SegmentedInputItem placeholder="0" value={rgb.b} onChange={onChannelChange("b")} className="w-5 flex-none" inputMode="numeric" pattern="[0-9]*" min={0} max={255} aria-label="Blue channel (0-255)" /> </SegmentedInput> <span className="size-3 rounded-sm border border-gray-6" style={{ backgroundColor: `rgb(${rgb.r}, ${rgb.g}, ${rgb.b})` }} aria-hidden /> </div> </div> ); }; ``` ### Vertical [#vertical] ```tsx export const Vertical = () => { const [address, setAddress] = React.useState({ street: "", city: "", zipCode: "", }); const onFieldChange = React.useCallback( (field: keyof typeof address) => (event: React.ChangeEvent<HTMLInputElement>) => { setAddress((prev) => ({ ...prev, [field]: event.target.value, })); }, [], ); return ( <div className="flex w-full max-w-sm flex-col gap-1"> <label className="text-sm font-medium text-gray-12"> Mailing Address </label> <SegmentedInput aria-label="Mailing address input" className="w-full" orientation="vertical" > <SegmentedInputItem aria-label="Street address" placeholder="Street Address" value={address.street} onChange={onFieldChange("street")} /> <SegmentedInputItem aria-label="City" placeholder="City" value={address.city} onChange={onFieldChange("city")} /> <SegmentedInputItem aria-label="ZIP code" placeholder="ZIP Code" value={address.zipCode} onChange={onFieldChange("zipCode")} /> </SegmentedInput> <p className="text-xs text-gray-11"> Tab between fields to move through the vertical segments. </p> </div> ); }; ``` ### Sizes [#sizes] ```tsx export const Sizes = () => ( <div className="flex w-full max-w-sm flex-col gap-2"> <SegmentedInput size="sm" className="w-full" aria-label="Small size"> <SegmentedInputItem placeholder="Small" aria-label="Small first" /> <SegmentedInputItem placeholder="Small" aria-label="Small second" /> </SegmentedInput> <SegmentedInput size="default" className="w-full" aria-label="Default size"> <SegmentedInputItem placeholder="Default" aria-label="Default first" /> <SegmentedInputItem placeholder="Default" aria-label="Default second" /> </SegmentedInput> <SegmentedInput size="lg" className="w-full" aria-label="Large size"> <SegmentedInputItem placeholder="Large" aria-label="Large first" /> <SegmentedInputItem placeholder="Large" aria-label="Large second" /> </SegmentedInput> </div> ) ``` ### Invalid [#invalid] ```tsx export const Invalid = () => ( <div className="flex w-full max-w-sm flex-col gap-1"> <label className="text-sm font-medium text-gray-12">Invalid state</label> <SegmentedInput invalid className="w-full" aria-label="Invalid segments"> <SegmentedInputItem defaultValue="12" aria-label="Part one" /> <SegmentedInputItem defaultValue="ab" aria-label="Part two" /> <SegmentedInputItem defaultValue="" placeholder="Required" aria-label="Part three" /> </SegmentedInput> </div> ) ``` # Select (/docs/components/select) ## Preview [#preview] <ComponentPreview name="select-demo" description="A select component that allows users to select a value from a list of options."> ```tsx import { useState } from "react"; import { Select, SelectTrigger, SelectValue, SelectIcon, SelectContent, SelectViewport, SelectItem, SelectItemText, SelectItemIndicator, SelectGroup, SelectLabel, SelectSeparator, SelectScrollUpButton, SelectScrollDownButton, SelectArrow, } from "@/components/ui/Select"; import { Label } from "@/components/ui/Label"; export function SelectDemo() { const [value, setValue] = useState("apricot"); return ( <div className="space-y-1"> <Label>Choose a fruit</Label> <Select value={value} onValueChange={setValue}> <SelectTrigger className="w-16"> <SelectValue placeholder="Select a fruit..." /> <SelectIcon /> </SelectTrigger> <SelectContent position="popper"> <SelectScrollUpButton /> <SelectViewport> <SelectItem value="apricot"> <SelectItemText>Apricot</SelectItemText> <SelectItemIndicator /> </SelectItem> <SelectItem value="banana"> <SelectItemText>Banana</SelectItemText> <SelectItemIndicator /> </SelectItem> <SelectItem value="orange"> <SelectItemText>Orange</SelectItemText> <SelectItemIndicator /> </SelectItem> <SelectItem value="grape"> <SelectItemText>Grape</SelectItemText> <SelectItemIndicator /> </SelectItem> <SelectItem value="mango"> <SelectItemText>Mango</SelectItemText> <SelectItemIndicator /> </SelectItem> </SelectViewport> <SelectScrollDownButton /> <SelectArrow /> </SelectContent> </Select> </div> ); } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/select ``` ### Manual [#manual] <Steps> <Step> Install the following dependencies: ```bash pnpm install @radix-ui/react-icons radix-ui ``` </Step> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the Select component into your `components/ui/Select.tsx` file. ```tsx "use client"; /** * @description Displays a list of options for the user to pick from—triggered by a button. / import as React from "react"; import { Select as SelectRadix } from "radix-ui"; import { CheckIcon, ChevronDownIcon, ChevronUpIcon, } from "@radix-ui/react-icons"; import { cn } from "@/utils/class-names"; function Select({ ...props }: React.ComponentProps<typeof SelectRadix.Root>) { return <SelectRadix.Root data-slot="select" {...props} />; } /** * Matches Input sm, default, and lg (`h-3`, `h-4`, `h-5`): 39, 52, and 65px. * Vertical padding is 0 so the spacing height is the border box. */ const selectTriggerSizeClassName = { sm: "box-border h-3 px-2 py-0", default: "box-border h-4 px-2 py-0", lg: "box-border h-5 px-2 py-0", } as const; type SelectTriggerSize = keyof typeof selectTriggerSizeClassName; function SelectTrigger({ className, size = "default", ...props }: React.ComponentProps<typeof SelectRadix.Trigger> & { size?: SelectTriggerSize; }) { return ( <SelectRadix.Trigger data-slot="select-trigger" data-size={size} className={cn( selectTriggerSizeClassName[size], "p font-normal leading-normal flex w-full items-center justify-between rounded-sm border border-gray-a6 bg-gray-2 text-gray-12 cursor-pointer hover:bg-gray-3 focus:outline-2 focus:outline-accent-9 focus:outline-offset-0 disabled:cursor-not-allowed disabled:opacity-50 disabled:hover:bg-gray-2 data-[placeholder]:text-gray-11", className )} {...props} /> ); } function SelectValue({ className, ...props }: React.ComponentProps<typeof SelectRadix.Value>) { return ( <SelectRadix.Value data-slot="select-value" className={cn(className)} {...props} /> ); } function SelectIcon({ className, ...props }: React.ComponentProps<typeof SelectRadix.Icon>) { return ( <SelectRadix.Icon data-slot="select-icon" className={cn(className, "text-gray-11")} {...props} > <ChevronDownIcon className="icon" /> </SelectRadix.Icon> ); } function SelectPortal({ ...props }: React.ComponentProps<typeof SelectRadix.Portal>) { return <SelectRadix.Portal data-slot="select-portal" {...props} />; } /** * Popup list. `SelectArrow` paints only when `position` is `"popper"`. * Radix ignores the arrow for the default `"item-aligned"` position. */ function SelectContent({ className, ...props }: React.ComponentProps<typeof SelectRadix.Content>) { return ( <SelectRadix.Portal> <SelectRadix.Content data-slot="select-content" collisionPadding={8} className={cn( className, "relative z-50 max-h-96 min-w-10 origin-(--radix-select-content-transform-origin) overflow-hidden rounded-sm border border-gray-a6 bg-gray-1 shadow-md data-[state=open]:animate-popover-show data-[state=closed]:animate-popover-hide" )} {...props} /> </SelectRadix.Portal> ); } function SelectViewport({ className, ...props }: React.ComponentProps<typeof SelectRadix.Viewport>) { return ( <SelectRadix.Viewport data-slot="select-viewport" className={cn(className, "p-0")} {...props} /> ); } function SelectItem({ className, children, ...props }: React.ComponentProps<typeof SelectRadix.Item>) { return ( <SelectRadix.Item data-slot="select-item" className={cn( className, "p font-normal leading-normal relative flex w-full cursor-pointer select-none items-center py-0.5 px-2 text-gray-12 outline-none hover:bg-accent-3 focus:bg-accent-3 focus:text-accent-12 focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-accent-8 data-[disabled]:pointer-events-none data-[disabled]:opacity-50" )} {...props} > {children} </SelectRadix.Item> ); } function SelectItemText({ className, ...props }: React.ComponentProps<typeof SelectRadix.ItemText>) { return ( <SelectRadix.ItemText data-slot="select-item-text" className={cn(className)} {...props} /> ); } function SelectItemIndicator({ className, ...props }: React.ComponentProps<typeof SelectRadix.ItemIndicator>) { return ( <SelectRadix.ItemIndicator data-slot="select-item-indicator" className={cn( className, "absolute left-0.5 top-0 bottom-0 flex items-center justify-center" )} {...props} > <CheckIcon className="text-accent-9" /> </SelectRadix.ItemIndicator> ); } function SelectGroup({ ...props }: React.ComponentProps<typeof SelectRadix.Group>) { return <SelectRadix.Group data-slot="select-group" {...props} />; } function SelectLabel({ className, ...props }: React.ComponentProps<typeof SelectRadix.Label>) { return ( <SelectRadix.Label data-slot="select-label" className={cn(className, "small py-0.5 px-2 text-gray-12")} {...props} /> ); } function SelectSeparator({ className, ...props }: React.ComponentProps<typeof SelectRadix.Separator>) { return ( <SelectRadix.Separator data-slot="select-separator" className={cn(className, "my-0.5 h-px bg-gray-a6")} {...props} /> ); } function SelectScrollUpButton({ className, ...props }: React.ComponentProps<typeof SelectRadix.ScrollUpButton>) { return ( <SelectRadix.ScrollUpButton data-slot="select-scroll-up-button" className={cn( className, "flex cursor-default items-center justify-center p-0.5" )} {...props} > <ChevronUpIcon className="icon text-gray-11" /> </SelectRadix.ScrollUpButton> ); } function SelectScrollDownButton({ className, ...props }: React.ComponentProps<typeof SelectRadix.ScrollDownButton>) { return ( <SelectRadix.ScrollDownButton data-slot="select-scroll-down-button" className={cn( className, "flex cursor-default items-center justify-center p-0.5" )} {...props} > <ChevronDownIcon className="icon text-gray-11" /> </SelectRadix.ScrollDownButton> ); } /** * Arrow linking the menu to the trigger. * Renders only when `SelectContent` uses `position="popper"`. * The default `item-aligned` position does not show this arrow. / function SelectArrow({ className, ...props }: React.ComponentProps<typeof SelectRadix.Arrow>) { return ( <SelectRadix.Arrow data-slot="select-arrow" className={cn(className, "fill-gray-1")} {...props} /> ); } export { Select, SelectPortal, SelectTrigger, SelectValue, SelectIcon, SelectContent, SelectViewport, SelectItem, SelectItemText, SelectItemIndicator, SelectGroup, SelectLabel, SelectSeparator, SelectScrollUpButton, SelectScrollDownButton, SelectArrow, }; export type { SelectTriggerSize }; ``` </Step> </Steps> ## Usage [#usage] ### Placeholder [#placeholder] ```tsx export const Placeholder = () => { return ( <div className="space-y-1"> <Label>Choose a fruit</Label> <Select> <SelectTrigger className="w-16"> <SelectValue placeholder="Select a fruit..." /> <SelectIcon /> </SelectTrigger> <SelectContent position="popper"> <SelectViewport> <SelectItem value="apricot"> <SelectItemText>Apricot</SelectItemText> <SelectItemIndicator /> </SelectItem> <SelectItem value="banana"> <SelectItemText>Banana</SelectItemText> <SelectItemIndicator /> </SelectItem> </SelectViewport> <SelectArrow /> </SelectContent> </Select> </div> ); }; ``` ### WithDefaultValue [#withdefaultvalue] ```tsx export const WithDefaultValue = () => { return ( <div className="space-y-1"> <Label>Choose a fruit</Label> <Select defaultValue="banana"> <SelectTrigger className="w-16"> <SelectValue placeholder="Select a fruit..." /> <SelectIcon /> </SelectTrigger> <SelectContent> <SelectViewport> <SelectItem value="apricot"> <SelectItemText>Apricot</SelectItemText> <SelectItemIndicator /> </SelectItem> <SelectItem value="banana"> <SelectItemText>Banana</SelectItemText> <SelectItemIndicator /> </SelectItem> <SelectItem value="orange"> <SelectItemText>Orange</SelectItemText> <SelectItemIndicator /> </SelectItem> <SelectItem value="grape"> <SelectItemText>Grape</SelectItemText> <SelectItemIndicator /> </SelectItem> </SelectViewport> </SelectContent> </Select> </div> ); }; ``` ### WithGroups [#withgroups] ```tsx export const WithGroups = () => { const [value, setValue] = useState("us"); return ( <div className="space-y-1"> <Label>Choose a country</Label> <Select value={value} onValueChange={setValue}> <SelectTrigger className="w-16"> <SelectValue placeholder="Select a country..." /> <SelectIcon /> </SelectTrigger> <SelectContent> <SelectViewport> <SelectGroup> <SelectLabel>Americas</SelectLabel> <SelectItem value="us"> <SelectItemText>United States</SelectItemText> <SelectItemIndicator /> </SelectItem> <SelectItem value="ca"> <SelectItemText>Canada</SelectItemText> <SelectItemIndicator /> </SelectItem> <SelectItem value="mx"> <SelectItemText>Mexico</SelectItemText> <SelectItemIndicator /> </SelectItem> </SelectGroup> <SelectSeparator /> <SelectGroup> <SelectLabel>Europe</SelectLabel> <SelectItem value="uk"> <SelectItemText>United Kingdom</SelectItemText> <SelectItemIndicator /> </SelectItem> <SelectItem value="fr"> <SelectItemText>France</SelectItemText> <SelectItemIndicator /> </SelectItem> <SelectItem value="de"> <SelectItemText>Germany</SelectItemText> <SelectItemIndicator /> </SelectItem> </SelectGroup> <SelectSeparator /> <SelectGroup> <SelectLabel>Asia</SelectLabel> <SelectItem value="jp"> <SelectItemText>Japan</SelectItemText> <SelectItemIndicator /> </SelectItem> <SelectItem value="cn"> <SelectItemText>China</SelectItemText> <SelectItemIndicator /> </SelectItem> <SelectItem value="kr"> <SelectItemText>South Korea</SelectItemText> <SelectItemIndicator /> </SelectItem> </SelectGroup> </SelectViewport> </SelectContent> </Select> </div> ); }; ``` ### WithDisabledItems [#withdisableditems] ```tsx export const WithDisabledItems = () => { const [value, setValue] = useState("apricot"); return ( <div className="space-y-1"> <Label>Choose a fruit</Label> <Select value={value} onValueChange={setValue}> <SelectTrigger className="w-16"> <SelectValue placeholder="Select a fruit..." /> <SelectIcon /> </SelectTrigger> <SelectContent> <SelectViewport> <SelectItem value="apricot"> <SelectItemText>Apricot</SelectItemText> <SelectItemIndicator /> </SelectItem> <SelectItem value="banana" disabled> <SelectItemText>Banana (disabled)</SelectItemText> <SelectItemIndicator /> </SelectItem> <SelectItem value="orange"> <SelectItemText>Orange</SelectItemText> <SelectItemIndicator /> </SelectItem> <SelectItem value="grape" disabled> <SelectItemText>Grape (disabled)</SelectItemText> <SelectItemIndicator /> </SelectItem> <SelectItem value="mango"> <SelectItemText>Mango</SelectItemText> <SelectItemIndicator /> </SelectItem> </SelectViewport> </SelectContent> </Select> </div> ); }; ``` ### Disabled [#disabled] ```tsx export const Disabled = () => { return ( <div className="space-y-1"> <Label>Choose a fruit (disabled)</Label> <Select disabled> <SelectTrigger className="w-16"> <SelectValue placeholder="Select a fruit..." /> <SelectIcon /> </SelectTrigger> <SelectContent> <SelectViewport> <SelectItem value="apricot"> <SelectItemText>Apricot</SelectItemText> <SelectItemIndicator /> </SelectItem> <SelectItem value="banana"> <SelectItemText>Banana</SelectItemText> <SelectItemIndicator /> </SelectItem> <SelectItem value="orange"> <SelectItemText>Orange</SelectItemText> <SelectItemIndicator /> </SelectItem> </SelectViewport> </SelectContent> </Select> </div> ); }; ``` ### WithLongList [#withlonglist] ```tsx export const WithLongList = () => { const [value, setValue] = useState("apricot"); const fruits = [ "Apricot", "Banana", "Orange", "Pineapple", "Grape", "Mango", "Strawberry", "Blueberry", "Raspberry", "Blackberry", "Cherry", "Peach", "Pear", "Plum", "Kiwi", "Watermelon", "Cantaloupe", "Honeydew", "Papaya", "Guava", ]; return ( <div className="space-y-1"> <Label>Choose a fruit</Label> <Select value={value} onValueChange={setValue}> <SelectTrigger className="w-16"> <SelectValue placeholder="Select a fruit..." /> <SelectIcon /> </SelectTrigger> <SelectContent position="popper"> <SelectScrollUpButton /> <SelectViewport> {fruits.map((fruit) => ( <SelectItem key={fruit} value={fruit.toLowerCase()}> <SelectItemText>{fruit}</SelectItemText> <SelectItemIndicator /> </SelectItem> ))} </SelectViewport> <SelectScrollDownButton /> <SelectArrow /> </SelectContent> </Select> </div> ); }; ``` ### Complex [#complex] ```tsx export const Complex = () => { const [value, setValue] = useState("us"); return ( <div className="space-y-1"> <Label>Choose a location</Label> <Select value={value} onValueChange={setValue}> <SelectTrigger className="w-16"> <SelectValue placeholder="Select a location..." /> <SelectIcon /> </SelectTrigger> <SelectContent position="popper"> <SelectScrollUpButton /> <SelectViewport> <SelectGroup> <SelectLabel>North America</SelectLabel> <SelectItem value="us"> <SelectItemText>United States</SelectItemText> <SelectItemIndicator /> </SelectItem> <SelectItem value="ca"> <SelectItemText>Canada</SelectItemText> <SelectItemIndicator /> </SelectItem> <SelectItem value="mx"> <SelectItemText>Mexico</SelectItemText> <SelectItemIndicator /> </SelectItem> </SelectGroup> <SelectSeparator /> <SelectGroup> <SelectLabel>Europe</SelectLabel> <SelectItem value="uk"> <SelectItemText>United Kingdom</SelectItemText> <SelectItemIndicator /> </SelectItem> <SelectItem value="fr"> <SelectItemText>France</SelectItemText> <SelectItemIndicator /> </SelectItem> <SelectItem value="de"> <SelectItemText>Germany</SelectItemText> <SelectItemIndicator /> </SelectItem> <SelectItem value="it"> <SelectItemText>Italy</SelectItemText> <SelectItemIndicator /> </SelectItem> <SelectItem value="es" disabled> <SelectItemText>Spain (disabled)</SelectItemText> <SelectItemIndicator /> </SelectItem> </SelectGroup> <SelectSeparator /> <SelectGroup> <SelectLabel>Asia Pacific</SelectLabel> <SelectItem value="jp"> <SelectItemText>Japan</SelectItemText> <SelectItemIndicator /> </SelectItem> <SelectItem value="cn"> <SelectItemText>China</SelectItemText> <SelectItemIndicator /> </SelectItem> <SelectItem value="kr"> <SelectItemText>South Korea</SelectItemText> <SelectItemIndicator /> </SelectItem> <SelectItem value="in"> <SelectItemText>India</SelectItemText> <SelectItemIndicator /> </SelectItem> <SelectItem value="au"> <SelectItemText>Australia</SelectItemText> <SelectItemIndicator /> </SelectItem> </SelectGroup> </SelectViewport> <SelectScrollDownButton /> <SelectArrow /> </SelectContent> </Select> </div> ); }; ``` ### Sizes [#sizes] ```tsx export const Sizes = () => { return ( <div className="flex flex-col items-start gap-2"> <Select defaultValue="apricot"> <SelectTrigger size="sm" className="w-16"> <SelectValue placeholder="Small" /> <SelectIcon /> </SelectTrigger> <SelectContent> <SelectViewport> <SelectItem value="apricot"> <SelectItemText>Apricot</SelectItemText> <SelectItemIndicator /> </SelectItem> <SelectItem value="banana"> <SelectItemText>Banana</SelectItemText> <SelectItemIndicator /> </SelectItem> </SelectViewport> </SelectContent> </Select> <Select defaultValue="apricot"> <SelectTrigger className="w-16"> <SelectValue placeholder="Default" /> <SelectIcon /> </SelectTrigger> <SelectContent> <SelectViewport> <SelectItem value="apricot"> <SelectItemText>Apricot</SelectItemText> <SelectItemIndicator /> </SelectItem> <SelectItem value="banana"> <SelectItemText>Banana</SelectItemText> <SelectItemIndicator /> </SelectItem> </SelectViewport> </SelectContent> </Select> <Select defaultValue="apricot"> <SelectTrigger size="lg" className="w-16"> <SelectValue placeholder="Large" /> <SelectIcon /> </SelectTrigger> <SelectContent> <SelectViewport> <SelectItem value="apricot"> <SelectItemText>Apricot</SelectItemText> <SelectItemIndicator /> </SelectItem> <SelectItem value="banana"> <SelectItemText>Banana</SelectItemText> <SelectItemIndicator /> </SelectItem> </SelectViewport> </SelectContent> </Select> </div> ); }; ``` # Selection Toolbar (/docs/components/selection-toolbar) ## Preview [#preview] <ComponentPreview name="selection-toolbar-demo" description="A floating toolbar that appears on text selection with formatting and utility actions."> ```tsx import as React from "react"; import { CopyIcon, FontBoldIcon, FontItalicIcon, Link2Icon, StrikethroughIcon, UnderlineIcon, } from "@radix-ui/react-icons"; import { SelectionToolbar, SelectionToolbarItem, SelectionToolbarSeparator, } from "@/components/ui/SelectionToolbar"; export function SelectionToolbarDemo() { const [copied, setCopied] = React.useState(""); return ( <div className="w-full max-w-lg"> <p className="text-gray-12"> {sampleCopy} </p> {copied ? ( <p className="mt-1 text-sm text-gray-11">Copied: {copied}</p> ) : null} <SelectionToolbar> <SelectionToolbarItem aria-label="Bold"> <FontBoldIcon className="icon" /> </SelectionToolbarItem> <SelectionToolbarItem aria-label="Italic"> <FontItalicIcon className="icon" /> </SelectionToolbarItem> <SelectionToolbarItem aria-label="Underline"> <UnderlineIcon className="icon" /> </SelectionToolbarItem> <SelectionToolbarSeparator /> <SelectionToolbarItem aria-label="Strikethrough"> <StrikethroughIcon className="icon" /> </SelectionToolbarItem> <SelectionToolbarItem aria-label="Link"> <Link2Icon className="icon" /> </SelectionToolbarItem> <SelectionToolbarSeparator /> <SelectionToolbarItem aria-label="Copy" onSelect={(text) => { void navigator.clipboard.writeText(text); setCopied(text); }} > <CopyIcon className="icon" /> </SelectionToolbarItem> </SelectionToolbar> </div> ); } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/selection-toolbar ``` ### Manual [#manual] <Steps> <Step> Install the following dependencies: ```bash pnpm install @floating-ui/react-dom @radix-ui/react-slot ``` </Step> <Step> Copy and paste the button component into your `components/ui/Button.tsx` file. ```tsx /** * @description Displays a button or a component that looks like a button. / import as React from "react"; import { Slot } from "@radix-ui/react-slot"; import { cva, type VariantProps } from "class-variance-authority"; import { cn } from "@/utils/class-names"; const buttonVariants = cva("button", { variants: { variant: { default: "button-fill", fill: "button-fill", pill: "button-pill border border-gray-6 text-gray-11 bg-gray-2 hover:bg-gray-3", link: "button-link", menu: "button-menu", }, size: { default: "h-4", xs: "h-2.5", sm: "h-3", md: "h-4", lg: "h-5", xl: "h-6", icon: "w-3 h-3 p-0", "icon-md": "w-4 h-4 p-0", }, }, defaultVariants: { variant: "default", size: "default", }, }); interface ButtonProps extends React.ComponentProps<"button">, VariantProps<typeof buttonVariants> { asChild?: boolean; isDisabled?: boolean; isLoading?: boolean; isLoadingText?: string | React.ReactNode; mode?: VariantProps<typeof buttonVariants>["variant"]; label?: string | React.ReactNode; } const Button = React.forwardRef<HTMLButtonElement, ButtonProps>( (props: ButtonProps, ref) => { const { className, variant, mode, size, asChild = false, isDisabled, isLoading, isLoadingText, children, label, ...rest } = props; const Comp = asChild ? Slot : "button"; const disabled = isDisabled || isLoading || props.disabled; const effectiveVariant = variant ?? mode; return ( <Comp data-slot="button" className={cn( buttonVariants({ variant: effectiveVariant, size, className }), disabled && "opacity-50 cursor-not-allowed" )} ref={ref} disabled={disabled} {...rest} > {asChild ? ( children ) : ( <> {isLoading && isLoadingText ? isLoadingText : <>{label}{children}</>} </> )} </Comp> ); } ); Button.displayName = "Button"; export { Button, buttonVariants }; export type { ButtonProps }; export default Button; ``` </Step> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the compose refs utility into your `utils/compose-refs.tsx` file. ```tsx /** * @see https://github.com/radix-ui/primitives/blob/main/packages/react/compose-refs/src/compose-refs.tsx / import as React from "react"; type PossibleRef<T> = React.Ref<T> | undefined; /** * Set a given ref to a given value * This utility takes care of different types of refs: callback refs and RefObject(s) */ function setRef<T>(ref: PossibleRef<T>, value: T) { if (typeof ref === "function") { return ref(value); } if (ref !== null && ref !== undefined) { ref.current = value; } } /** * A utility to compose multiple refs together * Accepts callback refs and RefObject(s) */ function composeRefs<T>(...refs: PossibleRef<T>[]): React.RefCallback<T> { return (node) => { let hasCleanup = false; const cleanups = refs.map((ref) => { const cleanup = setRef(ref, node); if (!hasCleanup && typeof cleanup === "function") { hasCleanup = true; } return cleanup; }); // React <19 will log an error to the console if a callback ref returns a // value. We don't use ref cleanups internally so this will only happen if a // user's ref callback returns a value, which we only expect if they are // using the cleanup functionality added in React 19. if (hasCleanup) { return () => { for (let i = 0; i < cleanups.length; i++) { const cleanup = cleanups[i]; if (typeof cleanup === "function") { cleanup(); } else { setRef(refs[i], null); } } }; } }; } /** * A custom hook that composes multiple refs * Accepts callback refs and RefObject(s) / function useComposedRefs<T>(...refs: PossibleRef<T>[]): React.RefCallback<T> { // biome-ignore lint/correctness/useExhaustiveDependencies: we want to memoize by all values return React.useCallback(composeRefs(...refs), refs); } export { composeRefs, useComposedRefs }; ``` </Step> <Step> Copy and paste the use as ref hook into your `hooks/use-as-ref.ts` file. ```ts import as React from "react"; import { useIsomorphicLayoutEffect } from "@/hooks/use-isomorphic-layout-effect"; function useAsRef<T>(props: T) { const ref = React.useRef<T>(props); useIsomorphicLayoutEffect(() => { ref.current = props; }); return ref; } export { useAsRef }; ``` </Step> <Step> Copy and paste the use isomorphic layout effect hook into your `hooks/use-isomorphic-layout-effect.ts` file. ```ts import * as React from "react"; const useIsomorphicLayoutEffect = typeof window !== "undefined" ? React.useLayoutEffect : React.useEffect; export { useIsomorphicLayoutEffect }; ``` </Step> <Step> Copy and paste the use lazy ref hook into your `hooks/use-lazy-ref.ts` file. ```ts import * as React from "react"; function useLazyRef<T>(fn: () => T) { const ref = React.useRef<T | null>(null); if (ref.current === null) { ref.current = fn(); } return ref as React.RefObject<T>; } export { useLazyRef }; ``` </Step> <Step> Copy and paste the SelectionToolbar component into your `components/ui/SelectionToolbar.tsx` file. ```tsx "use client"; /** * @description A floating toolbar that appears on text selection with formatting and utility actions. / import as React from "react"; import * as ReactDOM from "react-dom"; import { autoUpdate, flip, hide, limitShift, type Middleware, offset, type Placement, shift, size, useFloating, type VirtualElement, } from "@floating-ui/react-dom"; import { Slot } from "@radix-ui/react-slot"; import { useComposedRefs } from "@/utils/compose-refs"; import { cn } from "@/utils/class-names"; import { useAsRef } from "@/hooks/use-as-ref"; import { useIsomorphicLayoutEffect } from "@/hooks/use-isomorphic-layout-effect"; import { useLazyRef } from "@/hooks/use-lazy-ref"; import { Button } from "@/components/ui/Button"; const ROOT_NAME = "SelectionToolbar"; const ITEM_NAME = "SelectionToolbarItem"; type Side = "top" | "right" | "bottom" | "left"; type Align = "start" | "center" | "end"; type Boundary = Element | null; interface DivProps extends React.ComponentProps<"div"> { asChild?: boolean; } type ItemElement = React.ComponentRef<typeof Button>; function getSideAndAlignFromPlacement(placement: Placement) { const [side, align = "center"] = placement.split("-"); return [side as Side, align as Align] as const; } function isNotNull<T>(value: T | null): value is T { return value !== null; } interface SelectionRect { top: number; left: number; width: number; height: number; } interface StoreState { open: boolean; selectedText: string; selectionRect: SelectionRect | null; } interface Store { subscribe: (callback: () => void) => () => void; getState: () => StoreState; setState: <K extends keyof StoreState>(key: K, value: StoreState[K]) => void; notify: () => void; batch: (fn: () => void) => void; } const StoreContext = React.createContext<Store | null>(null); function useStoreContext(consumerName: string) { const context = React.useContext(StoreContext); if (!context) { throw new Error(`\`${consumerName}\` must be used within \`${ROOT_NAME}\``); } return context; } function useStore<T>( selector: (state: StoreState) => T, ogStore?: Store | null, ): T { const contextStore = React.useContext(StoreContext); const store = ogStore ?? contextStore; if (!store) { throw new Error(`\`useStore\` must be used within \`${ROOT_NAME}\``); } const getSnapshot = React.useCallback( () => selector(store.getState()), [store, selector], ); return React.useSyncExternalStore(store.subscribe, getSnapshot, getSnapshot); } interface SelectionToolbarProps extends DivProps { open?: boolean; onOpenChange?: (open: boolean) => void; onSelectionChange?: (text: string) => void; container?: HTMLElement | React.RefObject<HTMLElement | null> | null; portalContainer?: Element | DocumentFragment | null; side?: Side; sideOffset?: number; align?: Align; alignOffset?: number; avoidCollisions?: boolean; collisionBoundary?: Boundary | Boundary[]; collisionPadding?: number | Partial<Record<Side, number>>; sticky?: "partial" | "always"; hideWhenDetached?: boolean; updatePositionStrategy?: "optimized" | "always"; } function SelectionToolbar(props: SelectionToolbarProps) { const { open: openProp, onOpenChange, onSelectionChange, container: containerProp, portalContainer: portalContainerProp, side = "top", sideOffset = 13, align = "center", alignOffset = 0, avoidCollisions = true, collisionBoundary = [], collisionPadding: collisionPaddingProp = 0, sticky = "partial", hideWhenDetached = false, updatePositionStrategy = "optimized", className, style, asChild, ...rootProps } = props; const listenersRef = useLazyRef(() => new Set<() => void>()); const stateRef = useLazyRef<StoreState>(() => ({ open: openProp ?? false, selectedText: "", selectionRect: null, })); const propsRef = useAsRef({ onOpenChange, onSelectionChange, }); const getContainer = React.useCallback((): HTMLElement | null => { if (containerProp === undefined || containerProp === null) return null; if (typeof containerProp === "object" && "current" in containerProp) { return containerProp.current; } return containerProp; }, [containerProp]); const store = React.useMemo<Store>(() => { let isBatching = false; const storeApi: Store = { subscribe: (callback) => { listenersRef.current.add(callback); return () => { listenersRef.current.delete(callback); }; }, getState: () => stateRef.current, setState: (key, value) => { if (Object.is(stateRef.current[key], value)) return; if (key === "open" && typeof value === "boolean") { stateRef.current.open = value; propsRef.current.onOpenChange?.(value); } else if (key === "selectedText" && typeof value === "string") { stateRef.current.selectedText = value; propsRef.current.onSelectionChange?.(value); } else { stateRef.current[key] = value; } if (!isBatching) { storeApi.notify(); } }, notify: () => { for (const cb of listenersRef.current) { cb(); } }, batch: (fn: () => void) => { if (isBatching) { fn(); return; } isBatching = true; try { fn(); } finally { isBatching = false; storeApi.notify(); } }, }; return storeApi; }, [listenersRef, stateRef, propsRef]); useIsomorphicLayoutEffect(() => { if (openProp !== undefined) { store.setState("open", openProp); } }, [openProp, store]); const open = useStore((state) => state.open, store); const selectionRect = useStore((state) => state.selectionRect, store); const rafRef = React.useRef<number | null>(null); const mounted = React.useSyncExternalStore( () => () => {}, () => true, () => false, ); const virtualElement = React.useMemo<VirtualElement | null>(() => { if (!selectionRect) return null; return { getBoundingClientRect: () => ({ x: selectionRect.left, y: selectionRect.top, width: selectionRect.width, height: selectionRect.height, top: selectionRect.top, left: selectionRect.left, right: selectionRect.left + selectionRect.width, bottom: selectionRect.top + selectionRect.height, }), }; }, [selectionRect]); const transformOrigin = React.useMemo<Middleware>( () => ({ name: "transformOrigin", fn(data) { const { placement, rects } = data; const [placedSide, placedAlign] = getSideAndAlignFromPlacement(placement); const noArrowAlign = { start: "0%", center: "50%", end: "100%" }[ placedAlign ]; let x = ""; let y = ""; if (placedSide === "bottom") { x = noArrowAlign; y = "0px"; } else if (placedSide === "top") { x = noArrowAlign; y = `${rects.floating.height}px`; } else if (placedSide === "right") { x = "0px"; y = noArrowAlign; } else if (placedSide === "left") { x = `${rects.floating.width}px`; y = noArrowAlign; } return { data: { x, y } }; }, }), [], ); const desiredPlacement = React.useMemo( () => (side + (align !== "center" ? `-${align}` : "")) as Placement, [side, align], ); const collisionPadding = React.useMemo( () => typeof collisionPaddingProp === "number" ? collisionPaddingProp : { top: 0, right: 0, bottom: 0, left: 0, ...collisionPaddingProp }, [collisionPaddingProp], ); const boundary = React.useMemo( () => Array.isArray(collisionBoundary) ? collisionBoundary : [collisionBoundary], [collisionBoundary], ); const hasExplicitBoundaries = boundary.length > 0; const detectOverflowOptions = React.useMemo( () => ({ padding: collisionPadding, boundary: boundary.filter(isNotNull), altBoundary: hasExplicitBoundaries, }), [collisionPadding, boundary, hasExplicitBoundaries], ); const sizeMiddleware = React.useMemo( () => size({ ...detectOverflowOptions, apply: ({ elements, rects, availableWidth, availableHeight }) => { const { width: anchorWidth, height: anchorHeight } = rects.reference; const contentStyle = elements.floating.style; contentStyle.setProperty( "--selection-toolbar-available-width", `${availableWidth}px`, ); contentStyle.setProperty( "--selection-toolbar-available-height", `${availableHeight}px`, ); contentStyle.setProperty( "--selection-toolbar-anchor-width", `${anchorWidth}px`, ); contentStyle.setProperty( "--selection-toolbar-anchor-height", `${anchorHeight}px`, ); }, }), [detectOverflowOptions], ); const middleware = React.useMemo<Middleware[]>( () => [ offset({ mainAxis: sideOffset, alignmentAxis: alignOffset }), avoidCollisions && shift({ mainAxis: true, crossAxis: false, limiter: sticky === "partial" ? limitShift() : undefined, ...detectOverflowOptions, }), avoidCollisions && flip({ ...detectOverflowOptions }), sizeMiddleware, transformOrigin, hideWhenDetached && hide({ strategy: "referenceHidden", ...detectOverflowOptions }), ].filter(Boolean) as Middleware[], [ sideOffset, alignOffset, avoidCollisions, sticky, detectOverflowOptions, sizeMiddleware, transformOrigin, hideWhenDetached, ], ); const { refs, floatingStyles, isPositioned, middlewareData } = useFloating({ open: open && !!virtualElement, placement: desiredPlacement, strategy: "fixed", middleware, whileElementsMounted: (reference, floating, update) => { return autoUpdate(reference, floating, update, { animationFrame: updatePositionStrategy === "always", }); }, elements: { reference: virtualElement, }, }); const closeToolbar = React.useCallback(() => { const state = store.getState(); if (state.open || state.selectedText || state.selectionRect) { store.batch(() => { store.setState("open", false); store.setState("selectedText", ""); store.setState("selectionRect", null); }); } }, [store]); const updateSelection = React.useCallback(() => { const selection = window.getSelection(); if (!selection || selection.rangeCount === 0) { closeToolbar(); return; } const text = selection.toString().trim(); if (!text) { closeToolbar(); return; } if (containerProp !== undefined) { const resolvedContainer = getContainer(); if (!resolvedContainer) return; const range = selection.getRangeAt(0); const commonAncestor = range.commonAncestorContainer; const element = commonAncestor.nodeType === Node.ELEMENT_NODE ? (commonAncestor as Element) : commonAncestor.parentElement; if (!element || !resolvedContainer.contains(element)) { closeToolbar(); return; } } const range = selection.getRangeAt(0); const rect = range.getBoundingClientRect(); const state = store.getState(); const hasChanges = state.selectedText !== text || !state.selectionRect || state.selectionRect.top !== rect.top || state.selectionRect.left !== rect.left || state.selectionRect.width !== rect.width || state.selectionRect.height !== rect.height || !state.open; if (hasChanges) { store.batch(() => { store.setState("selectedText", text); store.setState("selectionRect", { top: rect.top, left: rect.left, width: rect.width, height: rect.height, }); store.setState("open", true); }); } }, [containerProp, getContainer, store, closeToolbar]); const scheduleUpdate = React.useCallback(() => { if (rafRef.current !== null) return; rafRef.current = requestAnimationFrame(() => { if (store.getState().open) { updateSelection(); } rafRef.current = null; }); }, [store, updateSelection]); React.useEffect(() => { const container = getContainer() ?? document; function onMouseUp() { requestAnimationFrame(() => { updateSelection(); }); } function onSelectionChange() { const selection = window.getSelection(); if (!selection?.toString().trim()) { closeToolbar(); } } container.addEventListener("mouseup", onMouseUp); document.addEventListener("selectionchange", onSelectionChange); window.addEventListener("scroll", scheduleUpdate, { passive: true }); window.addEventListener("resize", scheduleUpdate, { passive: true }); return () => { container.removeEventListener("mouseup", onMouseUp); document.removeEventListener("selectionchange", onSelectionChange); window.removeEventListener("scroll", scheduleUpdate); window.removeEventListener("resize", scheduleUpdate); if (rafRef.current !== null) { cancelAnimationFrame(rafRef.current); rafRef.current = null; } }; }, [getContainer, updateSelection, closeToolbar, scheduleUpdate]); const clearSelection = React.useCallback(() => { const selection = window.getSelection(); if (selection) { selection.removeAllRanges(); } closeToolbar(); }, [closeToolbar]); React.useEffect(() => { if (!open) return; function onMouseDown(event: MouseEvent) { const target = event.target as Node; if (refs.floating.current && !refs.floating.current.contains(target)) { clearSelection(); } } function onKeyDown(event: KeyboardEvent) { if (event.key === "Escape") { clearSelection(); } } document.addEventListener("mousedown", onMouseDown); document.addEventListener("keydown", onKeyDown); return () => { document.removeEventListener("mousedown", onMouseDown); document.removeEventListener("keydown", onKeyDown); }; }, [open, refs.floating, clearSelection]); const portalContainer = portalContainerProp ?? (mounted ? globalThis.document?.body : null); if (!portalContainer || !open) return null; const RootPrimitive = asChild ? Slot : "div"; const origin = middlewareData.transformOrigin as | { x: string; y: string } | undefined; return ( <StoreContext.Provider value={store}> {ReactDOM.createPortal( <div ref={refs.setFloating} style={{ ...floatingStyles, transform: isPositioned ? floatingStyles.transform : "translate(0, -200%)", minWidth: "max-content", zIndex: 50, ...(middlewareData.hide?.referenceHidden && { visibility: "hidden", pointerEvents: "none", }), }} data-state={isPositioned ? "positioned" : "measuring"} > <RootPrimitive role="toolbar" aria-label="Text formatting toolbar" data-slot="selection-toolbar" data-state={open ? "open" : "closed"} {...rootProps} className={cn( "flex items-center gap-0.5 rounded-md border border-gray-6 bg-gray-1 px-0.5 py-0.5 outline-none animate-selection-toolbar-show", className, )} style={{ transformOrigin: origin ? `${origin.x} ${origin.y}` : undefined, animation: !isPositioned ? "none" : undefined, ...style, }} /> </div>, portalContainer, )} </StoreContext.Provider> ); } interface SelectionToolbarItemProps extends Omit< React.ComponentProps<typeof Button>, "onSelect" > { onSelect?: (text: string, event: Event) => void; } function SelectionToolbarItem(props: SelectionToolbarItemProps) { const { onSelect: onSelectProp, onClick: onClickProp, onPointerDown: onPointerDownProp, onPointerUp: onPointerUpProp, className, ref, ...itemProps } = props; const store = useStoreContext(ITEM_NAME); const propsRef = useAsRef({ onSelect: onSelectProp, onClick: onClickProp, onPointerDown: onPointerDownProp, onPointerUp: onPointerUpProp, }); const itemRef = React.useRef<ItemElement>(null); const composedRef = useComposedRefs(ref, itemRef); const pointerTypeRef = React.useRef<React.PointerEvent["pointerType"]>("touch"); const onSelect = React.useCallback(() => { const item = itemRef.current; if (!item) return; const text = store.getState().selectedText; const selectEvent = new CustomEvent("selectiontoolbar.select", { bubbles: true, cancelable: true, detail: { text }, }); item.addEventListener( "selectiontoolbar.select", (event) => propsRef.current.onSelect?.(text, event), { once: true, }, ); item.dispatchEvent(selectEvent); }, [propsRef, store]); const onPointerDown = React.useCallback( (event: React.PointerEvent<ItemElement>) => { pointerTypeRef.current = event.pointerType; propsRef.current.onPointerDown?.(event); if (event.pointerType === "mouse") { event.preventDefault(); } }, [propsRef], ); const onClick = React.useCallback( (event: React.MouseEvent<ItemElement>) => { propsRef.current.onClick?.(event); if (event.defaultPrevented) return; if (pointerTypeRef.current !== "mouse") { onSelect(); } }, [propsRef, onSelect], ); const onPointerUp = React.useCallback( (event: React.PointerEvent<ItemElement>) => { propsRef.current.onPointerUp?.(event); if (event.defaultPrevented) return; if (pointerTypeRef.current === "mouse") { onSelect(); } }, [propsRef, onSelect], ); return ( <Button type="button" data-slot="selection-toolbar-item" variant="pill" size="icon" {...itemProps} className={className} ref={composedRef} onPointerDown={onPointerDown} onClick={onClick} onPointerUp={onPointerUp} /> ); } function SelectionToolbarSeparator(props: DivProps) { const { asChild, className, ...separatorProps } = props; const SeparatorPrimitive = asChild ? Slot : "div"; return ( <SeparatorPrimitive role="separator" aria-orientation="vertical" aria-hidden="true" data-slot="selection-toolbar-separator" {...separatorProps} className={cn("h-3 w-px bg-gray-6", className)} /> ); } export { SelectionToolbar, SelectionToolbarItem, type SelectionToolbarProps, SelectionToolbarSeparator, useStore as useSelectionToolbar, }; ``` </Step> </Steps> ## Usage [#usage] ### SelectionInfo [#selectioninfo] ```tsx export const SelectionInfo = () => { const [selectedText, setSelectedText] = React.useState(""); const words = selectedText.trim() ? selectedText.split(/\s+/).length : 0; const characters = selectedText.length; return ( <div className="w-full max-w-lg"> <p className="text-gray-12"> Highlight a phrase to see word and character counts in the toolbar. </p> <p className="mt-1 text-sm text-gray-11"> {selectedText ? `${words} words · ${characters} characters` : "No selection"} </p> <SelectionToolbar onSelectionChange={setSelectedText}> <span className="px-1 text-xs tabular-nums text-gray-11"> {words}w · {characters}c </span> <SelectionToolbarSeparator /> <SelectionToolbarItem aria-label="Copy" onSelect={(text) => { void navigator.clipboard.writeText(text); }} > <CopyIcon className="icon" /> </SelectionToolbarItem> </SelectionToolbar> </div> ); }; ``` ### ScopedContainer [#scopedcontainer] ```tsx export const ScopedContainer = () => { const containerRef = React.useRef<HTMLDivElement>(null); return ( <div className="flex w-full max-w-lg flex-col gap-1"> <div ref={containerRef} className="rounded-md border border-gray-6 bg-gray-2 p-1" > <p className="text-sm text-gray-12"> Selection inside this card opens the toolbar. Text outside it does not. </p> </div> <p className="text-sm text-gray-11"> This paragraph is outside the scoped container, so selecting it will not show the toolbar. </p> <SelectionToolbar container={containerRef}> <SelectionToolbarItem aria-label="Bold"> <FontBoldIcon className="icon" /> </SelectionToolbarItem> <SelectionToolbarItem aria-label="Italic"> <FontItalicIcon className="icon" /> </SelectionToolbarItem> <SelectionToolbarSeparator /> <SelectionToolbarItem aria-label="Copy" onSelect={(text) => { void navigator.clipboard.writeText(text); }} > <CopyIcon className="icon" /> </SelectionToolbarItem> </SelectionToolbar> </div> ); }; ``` # Separator (/docs/components/separator) ## Preview [#preview] <ComponentPreview name="separator-demo" description="A separator component that allows users to separate content."> ```tsx import { Separator } from "@/components/ui/Separator"; export function SeparatorDemo() { return ( <div> <div className="space-y-1"> <h4 className="text-sm leading-none font-medium">Radix Primitives</h4> <p className="text-gray-a11 text-sm"> An open-source UI component library. </p> </div> <Separator className="my-1" /> <div className="flex h-1 items-center space-x-1 text-sm"> <div>Blog</div> <Separator orientation="vertical" /> <div>Docs</div> <Separator orientation="vertical" /> <div>Source</div> </div> </div> ); } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/separator ``` ### Manual [#manual] <Steps> <Step> Install the following dependencies: ```bash pnpm install radix-ui ``` </Step> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the Separator component into your `components/ui/Separator.tsx` file. ```tsx "use client" import * as React from "react" import {Separator as SeparatorPrimitive} from "radix-ui" import { cn } from "@/utils/class-names" function Separator({ className, orientation = "horizontal", decorative = true, ...props }: React.ComponentProps<typeof SeparatorPrimitive.Root>) { return ( <SeparatorPrimitive.Root data-slot="separator" decorative={decorative} orientation={orientation} className={cn( "bg-gray-a6 shrink-0 data-[orientation=horizontal]:h-px data-[orientation=horizontal]:w-full data-[orientation=vertical]:h-full data-[orientation=vertical]:w-px", className )} {...props} /> ) } export { Separator } ``` </Step> </Steps> # Shape (/docs/components/shape) ## Preview [#preview] <ComponentPreview name="shape-demo" description="A set of shapes that can mask an image and morph between each other."> ```tsx import { Shape } from "@/components/ui/Shape"; export function ShapeDemo() { return ( <div className="flex flex-wrap items-center gap-1"> <Shape name="circle" /> <Shape name="square" /> <Shape name="diamond" /> <Shape name="arch" /> <Shape name="pill" /> </div> ); } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/shape ``` ### Manual [#manual] <Steps> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the Shape component into your `components/ui/Shape.tsx` file. ```tsx "use client"; import * as React from "react"; import { cn } from "@/utils/class-names"; const shapePaths = { circle: "circle(50% at 50% 50%)", square: "inset(0% round 12%)", diamond: "polygon(50% 0%, 100% 50%, 50% 100%, 0% 50%)", arch: "polygon(0% 100%, 0% 42%, 18% 14%, 50% 0%, 82% 14%, 100% 42%, 100% 100%)", pill: "inset(18% 0% round 999px)", } as const; type ShapeName = keyof typeof shapePaths; function Shape({ className, name = "circle", size = "default", ...props }: React.ComponentProps<"div"> & { name?: ShapeName; size?: "sm" | "default" | "lg"; }) { return ( <div data-slot="shape" data-shape={name} data-size={size} style={{ clipPath: shapePaths[name] }} className={cn( "bg-accent-9 transition duration-300 ease-in-out motion-reduce:transition-none", size === "sm" && "size-3", size === "default" && "size-8", size === "lg" && "size-12", className, )} {...props} /> ); } function ShapeMorph({ names = ["circle", "diamond", "arch", "pill", "square"], interval = 900, }: { names?: ShapeName[]; interval?: number; }) { const [index, setIndex] = React.useState(0); React.useEffect(() => { const query = window.matchMedia("(prefers-reduced-motion: reduce)"); if (query.matches) return; const timer = window.setInterval(() => { setIndex((current) => (current + 1) % names.length); }, interval); return () => window.clearInterval(timer); }, [interval, names.length]); return <Shape name={names[index]} size="sm" />; } export { Shape, ShapeMorph, shapePaths }; export type { ShapeName }; ``` </Step> </Steps> ## Usage [#usage] ### Mask [#mask] ```tsx export const Mask = () => { return <Shape name="arch" size="lg" role="img" aria-label="Arch mask" />; }; ``` # Sheet (/docs/components/sheet) ## Preview [#preview] <ComponentPreview name="sheet-demo" description="A slide-out panel that overlays the page, with optional header, footer, title, and description. Opens from a trigger (e.g. button)."> ```tsx import { Button } from "@/components/ui/Button"; import { Sheet, SheetTrigger, SheetContent, SheetHeader, SheetTitle, SheetDescription, } from "@/components/ui/Sheet"; export function SheetDemo() { return ( <Sheet> <SheetTrigger asChild> <Button>Open sheet</Button> </SheetTrigger> <SheetContent> <SheetHeader> <SheetTitle>Sheet title</SheetTitle> <SheetDescription> A short description of the sheet content. </SheetDescription> </SheetHeader> </SheetContent> </Sheet> ); } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/sheet ``` ### Manual [#manual] <Steps> <Step> Install the following dependencies: ```bash pnpm install @radix-ui/react-icons radix-ui ``` </Step> <Step> Copy and paste the button component into your `components/ui/Button.tsx` file. ```tsx /** * @description Displays a button or a component that looks like a button. / import as React from "react"; import { Slot } from "@radix-ui/react-slot"; import { cva, type VariantProps } from "class-variance-authority"; import { cn } from "@/utils/class-names"; const buttonVariants = cva("button", { variants: { variant: { default: "button-fill", fill: "button-fill", pill: "button-pill border border-gray-6 text-gray-11 bg-gray-2 hover:bg-gray-3", link: "button-link", menu: "button-menu", }, size: { default: "h-4", xs: "h-2.5", sm: "h-3", md: "h-4", lg: "h-5", xl: "h-6", icon: "w-3 h-3 p-0", "icon-md": "w-4 h-4 p-0", }, }, defaultVariants: { variant: "default", size: "default", }, }); interface ButtonProps extends React.ComponentProps<"button">, VariantProps<typeof buttonVariants> { asChild?: boolean; isDisabled?: boolean; isLoading?: boolean; isLoadingText?: string | React.ReactNode; mode?: VariantProps<typeof buttonVariants>["variant"]; label?: string | React.ReactNode; } const Button = React.forwardRef<HTMLButtonElement, ButtonProps>( (props: ButtonProps, ref) => { const { className, variant, mode, size, asChild = false, isDisabled, isLoading, isLoadingText, children, label, ...rest } = props; const Comp = asChild ? Slot : "button"; const disabled = isDisabled || isLoading || props.disabled; const effectiveVariant = variant ?? mode; return ( <Comp data-slot="button" className={cn( buttonVariants({ variant: effectiveVariant, size, className }), disabled && "opacity-50 cursor-not-allowed" )} ref={ref} disabled={disabled} {...rest} > {asChild ? ( children ) : ( <> {isLoading && isLoadingText ? isLoadingText : <>{label}{children}</>} </> )} </Comp> ); } ); Button.displayName = "Button"; export { Button, buttonVariants }; export type { ButtonProps }; export default Button; ``` </Step> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the Sheet component into your `components/ui/Sheet.tsx` file. ```tsx "use client"; import * as React from "react"; import { Dialog as SheetPrimitive } from "radix-ui"; import { Cross2Icon } from "@radix-ui/react-icons" import { cn } from "@/utils/class-names"; import Button from "@/components/ui/Button"; function Sheet({ ...props }: React.ComponentProps<typeof SheetPrimitive.Root>) { return <SheetPrimitive.Root data-slot="sheet" {...props} />; } function SheetTrigger({ ...props }: React.ComponentProps<typeof SheetPrimitive.Trigger>) { return <SheetPrimitive.Trigger data-slot="sheet-trigger" {...props} />; } function SheetClose({ ...props }: React.ComponentProps<typeof SheetPrimitive.Close>) { return <SheetPrimitive.Close data-slot="sheet-close" {...props} />; } function SheetPortal({ ...props }: React.ComponentProps<typeof SheetPrimitive.Portal>) { return <SheetPrimitive.Portal data-slot="sheet-portal" {...props} />; } function SheetOverlay({ className, ...props }: React.ComponentProps<typeof SheetPrimitive.Overlay>) { return ( <SheetPrimitive.Overlay data-slot="sheet-overlay" className={cn( "aura-overlay z-50", className )} {...props} /> ); } function SheetContent({ className, children, side = "right", ...props }: React.ComponentProps<typeof SheetPrimitive.Content> & { side?: "top" | "right" | "bottom" | "left"; }) { return ( <SheetPortal> <SheetOverlay /> <SheetPrimitive.Content data-slot="sheet-content" className={cn( "bg-gray-1 fixed z-50 flex flex-col gap-1 shadow-lg", side === "right" && "data-[state=open]:animate-sheet-right-open data-[state=closed]:animate-sheet-right-closed inset-y-0 right-0 h-full w-3/4 border-l sm:max-w-sm border-gray-a6", side === "left" && "data-[state=open]:animate-sheet-left-open data-[state=closed]:animate-sheet-left-closed inset-y-0 left-0 h-full w-3/4 border-r sm:max-w-sm border-gray-a6", side === "top" && "data-[state=open]:animate-sheet-top-open data-[state=closed]:animate-sheet-top-closed inset-x-0 top-0 h-auto border-b border-gray-a6", side === "bottom" && "data-[state=open]:animate-sheet-bottom-open data-[state=closed]:animate-sheet-bottom-closed inset-x-0 bottom-0 h-auto border-t border-gray-a6", className )} {...props} > {children} <SheetPrimitive.Close className=" absolute top-0.5 right-0.5" asChild> <Button mode="link"> <Cross2Icon className="icon" /> <span className="sr-only">Close</span> </Button> </SheetPrimitive.Close> </SheetPrimitive.Content> </SheetPortal> ); } function SheetHeader({ className, ...props }: React.ComponentProps<"div">) { return ( <div data-slot="sheet-header" className={cn("flex flex-col gap-1.5 p-2", className)} {...props} /> ); } function SheetFooter({ className, ...props }: React.ComponentProps<"div">) { return ( <div data-slot="sheet-footer" className={cn("mt-auto flex flex-col gap-1 p-2", className)} {...props} /> ); } function SheetTitle({ className, ...props }: React.ComponentProps<typeof SheetPrimitive.Title>) { return ( <SheetPrimitive.Title data-slot="sheet-title" className={cn("text-gray-12 font-semibold", className)} {...props} /> ); } function SheetDescription({ className, ...props }: React.ComponentProps<typeof SheetPrimitive.Description>) { return ( <SheetPrimitive.Description data-slot="sheet-description" className={cn("text-gray-11 text-sm", className)} {...props} /> ); } export { Sheet, SheetTrigger, SheetClose, SheetContent, SheetHeader, SheetFooter, SheetTitle, SheetDescription, }; ``` </Step> </Steps> # Side Sheet (/docs/components/side-sheet) ## Preview [#preview] <ComponentPreview name="side-sheet-demo" description="A side panel that sits beside the content, with no overlay."> ```tsx import { SideSheet, SideSheetMain, SideSheetPanel } from "@/components/ui/SideSheet"; export function SideSheetDemo() { return ( <div className="h-24 overflow-hidden rounded-sm border border-gray-6"> <SideSheet> <SideSheetMain> <div className="bg-gray-2 p-1.5"> <p className="m-0">Page content stays beside the panel.</p> </div> </SideSheetMain> <SideSheetPanel label="Details"> <p className="m-0 font-medium">Details</p> <p className="m-0">No overlay. The panel sits next to the content.</p> </SideSheetPanel> </SideSheet> </div> ); } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/side-sheet ``` ### Manual [#manual] <Steps> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the SideSheet component into your `components/ui/SideSheet.tsx` file. ```tsx "use client"; import * as React from "react"; import { cn } from "@/utils/class-names"; function SideSheet({ className, ...props }: React.ComponentProps<"div">) { return ( <div data-slot="side-sheet" className={cn("flex h-full min-h-0 min-w-0", className)} {...props} /> ); } function SideSheetMain({ className, ...props }: React.ComponentProps<"div">) { return ( <div data-slot="side-sheet-main" className={cn("min-w-0 flex-1", className)} {...props} /> ); } function SideSheetPanel({ className, open = true, side = "end", label = "Side panel", ...props }: React.ComponentProps<"aside"> & { open?: boolean; side?: "start" | "end"; label?: string; }) { return ( <aside aria-label={label} data-slot="side-sheet-panel" data-state={open ? "open" : "closed"} hidden={!open} className={cn( "flex w-20 shrink-0 flex-col gap-1 bg-gray-1 p-1.5", side === "end" ? "order-2 border-s border-gray-6" : "order-1 border-e border-gray-6", className, )} {...props} /> ); } export { SideSheet, SideSheetMain, SideSheetPanel }; ``` </Step> </Steps> # Sidebar (/docs/components/sidebar) ## Preview [#preview] <ComponentPreview name="sidebar-demo" description="A collapsible side panel for app navigation and layout, with optional mobile sheet, icons, and persistent state."> ```tsx import { SidebarProvider, Sidebar, SidebarTrigger, SidebarHeader, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupLabel, SidebarMenu, SidebarMenuItem, SidebarMenuButton, SidebarMenuAction, SidebarMenuSub, SidebarMenuSubItem, SidebarMenuSubButton, SidebarInset, SidebarRail, } from "@/components/ui/Sidebar"; import { Collapsible, CollapsibleTrigger, CollapsibleContent, } from "@/components/ui/Collapsible"; import { DropdownMenu, DropdownMenuContent, DropdownMenuTrigger, DropdownMenuItem, DropdownMenuLabel, DropdownMenuSeparator, } from "@/components/ui/DropdownMenu"; import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/Avatar"; import { ImageIcon, CaretSortIcon, ChevronRightIcon, CodeIcon, GearIcon, DotsHorizontalIcon, Component1Icon, BookmarkIcon, FrameIcon, PieChartIcon, GlobeIcon, } from "@radix-ui/react-icons"; export function SidebarDemo() { return ( <SidebarProvider> <Sidebar collapsible="icon"> <SidebarHeader> <SidebarMenu> <SidebarMenuItem> <DropdownMenu> <DropdownMenuTrigger asChild> <SidebarMenuButton size="lg" tooltip="Acme Inc"> <div className="flex aspect-square size-2.5 items-center justify-center rounded-lg bg-accent-9 text-accent-1 group-data-[collapsible=icon]:size-3"> <ImageIcon className="icon" /> </div> <div className="grid flex-1 text-left text-sm leading-tight group-data-[collapsible=icon]:hidden"> <span className="truncate font-medium">Acme Inc</span> <span className="truncate text-xs text-gray-11">Enterprise</span> </div> <CaretSortIcon className="icon ml-auto group-data-[collapsible=icon]:hidden" /> </SidebarMenuButton> </DropdownMenuTrigger> <DropdownMenuContent align="start" className="w-(--sidebar-width)"> <DropdownMenuLabel>My accounts</DropdownMenuLabel> <DropdownMenuSeparator /> <DropdownMenuItem>Acme Inc</DropdownMenuItem> <DropdownMenuItem>Personal</DropdownMenuItem> </DropdownMenuContent> </DropdownMenu> </SidebarMenuItem> </SidebarMenu> </SidebarHeader> <SidebarContent> <SidebarGroup> <SidebarGroupLabel>Platform</SidebarGroupLabel> <SidebarMenu> <SidebarMenuItem> <Collapsible defaultOpen className="group/collapsible"> <CollapsibleTrigger asChild> <SidebarMenuButton tooltip="Playground"> <CodeIcon className="icon" /> <span>Playground</span> <ChevronRightIcon className="icon ml-auto transition-transform duration-200 group-data-[state=open]/collapsible:rotate-90 group-data-[collapsible=icon]:hidden" /> </SidebarMenuButton> </CollapsibleTrigger> <CollapsibleContent> <SidebarMenuSub> <SidebarMenuSubItem> <SidebarMenuSubButton href="#">History</SidebarMenuSubButton> </SidebarMenuSubItem> <SidebarMenuSubItem> <SidebarMenuSubButton href="#">Starred</SidebarMenuSubButton> </SidebarMenuSubItem> <SidebarMenuSubItem> <SidebarMenuSubButton href="#">Settings</SidebarMenuSubButton> </SidebarMenuSubItem> <SidebarMenuSubItem> <SidebarMenuSubButton href="#">Templates</SidebarMenuSubButton> </SidebarMenuSubItem> </SidebarMenuSub> </CollapsibleContent> </Collapsible> </SidebarMenuItem> <SidebarMenuItem> <Collapsible className="group/collapsible"> <CollapsibleTrigger asChild> <SidebarMenuButton tooltip="Models"> <Component1Icon className="icon" /> <span>Models</span> <ChevronRightIcon className="icon ml-auto transition-transform duration-200 group-data-[state=open]/collapsible:rotate-90 group-data-[collapsible=icon]:hidden" /> </SidebarMenuButton> </CollapsibleTrigger> <CollapsibleContent> <SidebarMenuSub> <SidebarMenuSubItem> <SidebarMenuSubButton href="#">All models</SidebarMenuSubButton> </SidebarMenuSubItem> <SidebarMenuSubItem> <SidebarMenuSubButton href="#">Custom</SidebarMenuSubButton> </SidebarMenuSubItem> <SidebarMenuSubItem> <SidebarMenuSubButton href="#">Favorites</SidebarMenuSubButton> </SidebarMenuSubItem> <SidebarMenuSubItem> <SidebarMenuSubButton href="#">Recent</SidebarMenuSubButton> </SidebarMenuSubItem> </SidebarMenuSub> </CollapsibleContent> </Collapsible> </SidebarMenuItem> <SidebarMenuItem> <Collapsible className="group/collapsible"> <CollapsibleTrigger asChild> <SidebarMenuButton tooltip="Documentation"> <BookmarkIcon className="icon" /> <span>Documentation</span> <ChevronRightIcon className="icon ml-auto transition-transform duration-200 group-data-[state=open]/collapsible:rotate-90 group-data-[collapsible=icon]:hidden" /> </SidebarMenuButton> </CollapsibleTrigger> <CollapsibleContent> <SidebarMenuSub> <SidebarMenuSubItem> <SidebarMenuSubButton href="#">Getting started</SidebarMenuSubButton> </SidebarMenuSubItem> <SidebarMenuSubItem> <SidebarMenuSubButton href="#">API reference</SidebarMenuSubButton> </SidebarMenuSubItem> <SidebarMenuSubItem> <SidebarMenuSubButton href="#">Guides</SidebarMenuSubButton> </SidebarMenuSubItem> <SidebarMenuSubItem> <SidebarMenuSubButton href="#">Changelog</SidebarMenuSubButton> </SidebarMenuSubItem> </SidebarMenuSub> </CollapsibleContent> </Collapsible> </SidebarMenuItem> <SidebarMenuItem> <Collapsible className="group/collapsible"> <CollapsibleTrigger asChild> <SidebarMenuButton tooltip="Settings"> <GearIcon className="icon" /> <span>Settings</span> <ChevronRightIcon className="icon ml-auto transition-transform duration-200 group-data-[state=open]/collapsible:rotate-90 group-data-[collapsible=icon]:hidden" /> </SidebarMenuButton> </CollapsibleTrigger> <CollapsibleContent> <SidebarMenuSub> <SidebarMenuSubItem> <SidebarMenuSubButton href="#">General</SidebarMenuSubButton> </SidebarMenuSubItem> <SidebarMenuSubItem> <SidebarMenuSubButton href="#">Team</SidebarMenuSubButton> </SidebarMenuSubItem> <SidebarMenuSubItem> <SidebarMenuSubButton href="#">Billing</SidebarMenuSubButton> </SidebarMenuSubItem> <SidebarMenuSubItem> <SidebarMenuSubButton href="#">Integrations</SidebarMenuSubButton> </SidebarMenuSubItem> </SidebarMenuSub> </CollapsibleContent> </Collapsible> </SidebarMenuItem> </SidebarMenu> </SidebarGroup> <SidebarGroup className="group-data-[collapsible=icon]:hidden"> <SidebarGroupLabel>Projects</SidebarGroupLabel> <SidebarMenu> <SidebarMenuItem> <SidebarMenuButton asChild tooltip="Design Engineering"> <a href="#"> <FrameIcon className="icon" /> <span>Design Engineering</span> </a> </SidebarMenuButton> <DropdownMenu> <DropdownMenuTrigger asChild> <SidebarMenuAction showOnHover aria-label="More options"> <DotsHorizontalIcon className="icon" /> <span className="sr-only">More</span> </SidebarMenuAction> </DropdownMenuTrigger> <DropdownMenuContent align="end"> <DropdownMenuItem>Edit</DropdownMenuItem> <DropdownMenuItem>Duplicate</DropdownMenuItem> <DropdownMenuSeparator /> <DropdownMenuItem>Archive</DropdownMenuItem> </DropdownMenuContent> </DropdownMenu> </SidebarMenuItem> <SidebarMenuItem> <SidebarMenuButton asChild tooltip="Sales & Marketing"> <a href="#"> <PieChartIcon className="icon" /> <span>Sales & Marketing</span> </a> </SidebarMenuButton> <DropdownMenu> <DropdownMenuTrigger asChild> <SidebarMenuAction showOnHover aria-label="More options"> <DotsHorizontalIcon className="icon" /> <span className="sr-only">More</span> </SidebarMenuAction> </DropdownMenuTrigger> <DropdownMenuContent align="end"> <DropdownMenuItem>Edit</DropdownMenuItem> <DropdownMenuItem>Duplicate</DropdownMenuItem> <DropdownMenuSeparator /> <DropdownMenuItem>Archive</DropdownMenuItem> </DropdownMenuContent> </DropdownMenu> </SidebarMenuItem> <SidebarMenuItem> <SidebarMenuButton asChild tooltip="Travel"> <a href="#"> <GlobeIcon className="icon" /> <span>Travel</span> </a> </SidebarMenuButton> <DropdownMenu> <DropdownMenuTrigger asChild> <SidebarMenuAction showOnHover aria-label="More options"> <DotsHorizontalIcon className="icon" /> <span className="sr-only">More</span> </SidebarMenuAction> </DropdownMenuTrigger> <DropdownMenuContent align="end"> <DropdownMenuItem>Edit</DropdownMenuItem> <DropdownMenuItem>Duplicate</DropdownMenuItem> <DropdownMenuSeparator /> <DropdownMenuItem>Archive</DropdownMenuItem> </DropdownMenuContent> </DropdownMenu> </SidebarMenuItem> <SidebarMenuItem> <SidebarMenuButton asChild tooltip="Analytics"> <a href="#"> <PieChartIcon className="icon" /> <span>Analytics</span> </a> </SidebarMenuButton> <DropdownMenu> <DropdownMenuTrigger asChild> <SidebarMenuAction showOnHover aria-label="More options"> <DotsHorizontalIcon className="icon" /> <span className="sr-only">More</span> </SidebarMenuAction> </DropdownMenuTrigger> <DropdownMenuContent align="end"> <DropdownMenuItem>Edit</DropdownMenuItem> <DropdownMenuItem>Duplicate</DropdownMenuItem> <DropdownMenuSeparator /> <DropdownMenuItem>Archive</DropdownMenuItem> </DropdownMenuContent> </DropdownMenu> </SidebarMenuItem> <SidebarMenuItem> <DropdownMenu> <DropdownMenuTrigger asChild> <SidebarMenuButton tooltip="More" className="text-gray-11"> <DotsHorizontalIcon className="icon text-gray-11" /> <span>More</span> <ChevronRightIcon className="icon ml-auto group-data-[collapsible=icon]:hidden" /> </SidebarMenuButton> </DropdownMenuTrigger> <DropdownMenuContent align="start" > <DropdownMenuLabel>Projects</DropdownMenuLabel> <DropdownMenuSeparator /> <DropdownMenuItem>New project</DropdownMenuItem> <DropdownMenuItem>Import project</DropdownMenuItem> <DropdownMenuItem>From template</DropdownMenuItem> <DropdownMenuSeparator /> <DropdownMenuItem>View all projects</DropdownMenuItem> </DropdownMenuContent> </DropdownMenu> </SidebarMenuItem> </SidebarMenu> </SidebarGroup> </SidebarContent> <SidebarFooter> <SidebarMenu> <SidebarMenuItem> <DropdownMenu> <DropdownMenuTrigger asChild> <SidebarMenuButton size="lg" tooltip="User menu"> <Avatar className="size-2.5 rounded-lg group-data-[collapsible=icon]:size-3"> <AvatarImage src="/avatars/shadcn.jpg" alt="shadcn" /> <AvatarFallback>SC</AvatarFallback> </Avatar> <div className="grid flex-1 text-left text-sm leading-tight group-data-[collapsible=icon]:hidden"> <span className="truncate font-medium">shadcn</span> <span className="truncate text-xs text-gray-11">m@example.com</span> </div> <CaretSortIcon className="icon ml-auto group-data-[collapsible=icon]:hidden" /> </SidebarMenuButton> </DropdownMenuTrigger> <DropdownMenuContent align="start" className="w-(--sidebar-width)"> <DropdownMenuLabel>My account</DropdownMenuLabel> <DropdownMenuSeparator /> <DropdownMenuItem>Profile</DropdownMenuItem> <DropdownMenuItem>Billing</DropdownMenuItem> <DropdownMenuItem>Settings</DropdownMenuItem> <DropdownMenuSeparator /> <DropdownMenuItem>Log out</DropdownMenuItem> </DropdownMenuContent> </DropdownMenu> </SidebarMenuItem> </SidebarMenu> </SidebarFooter> <SidebarRail /> </Sidebar> <SidebarInset> <header className="flex h-4 shrink-0 items-center gap-2 border-b border-gray-6 px-2"> <SidebarTrigger /> <div className="h-2.5 w-px bg-gray-6" /> <span className="text-sm text-gray-11">Main content area</span> </header> <div className="flex-1 p-4"> <p className="text-sm text-gray-11"> Resize the viewport or use the sidebar rail to collapse the sidebar. The header shows Acme Inc, Platform (Playground with sub-items, Models, Documentation, Settings), and Projects (Design Engineering, Sales & Marketing, Travel, More). Footer shows user menu. </p> </div> </SidebarInset> </SidebarProvider> ); } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/sidebar ``` ### Manual [#manual] <Steps> <Step> Install the following dependencies: ```bash pnpm install @radix-ui/react-icons @radix-ui/react-slot ``` </Step> <Step> Copy and paste the button component into your `components/ui/Button.tsx` file. ```tsx /** * @description Displays a button or a component that looks like a button. / import as React from "react"; import { Slot } from "@radix-ui/react-slot"; import { cva, type VariantProps } from "class-variance-authority"; import { cn } from "@/utils/class-names"; const buttonVariants = cva("button", { variants: { variant: { default: "button-fill", fill: "button-fill", pill: "button-pill border border-gray-6 text-gray-11 bg-gray-2 hover:bg-gray-3", link: "button-link", menu: "button-menu", }, size: { default: "h-4", xs: "h-2.5", sm: "h-3", md: "h-4", lg: "h-5", xl: "h-6", icon: "w-3 h-3 p-0", "icon-md": "w-4 h-4 p-0", }, }, defaultVariants: { variant: "default", size: "default", }, }); interface ButtonProps extends React.ComponentProps<"button">, VariantProps<typeof buttonVariants> { asChild?: boolean; isDisabled?: boolean; isLoading?: boolean; isLoadingText?: string | React.ReactNode; mode?: VariantProps<typeof buttonVariants>["variant"]; label?: string | React.ReactNode; } const Button = React.forwardRef<HTMLButtonElement, ButtonProps>( (props: ButtonProps, ref) => { const { className, variant, mode, size, asChild = false, isDisabled, isLoading, isLoadingText, children, label, ...rest } = props; const Comp = asChild ? Slot : "button"; const disabled = isDisabled || isLoading || props.disabled; const effectiveVariant = variant ?? mode; return ( <Comp data-slot="button" className={cn( buttonVariants({ variant: effectiveVariant, size, className }), disabled && "opacity-50 cursor-not-allowed" )} ref={ref} disabled={disabled} {...rest} > {asChild ? ( children ) : ( <> {isLoading && isLoadingText ? isLoadingText : <>{label}{children}</>} </> )} </Comp> ); } ); Button.displayName = "Button"; export { Button, buttonVariants }; export type { ButtonProps }; export default Button; ``` </Step> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the input component into your `components/ui/Input.tsx` file. ```tsx /** * @description Displays a form input field or a component that looks like an input field. / import as React from "react"; import { cn } from "@/utils/class-names"; /** * Matches Button sm, md, and lg (`h-3`, `h-4`, `h-5`). * Vertical padding is 0 so the spacing height is the border box, same as Button. / const inputSizeClassName = { sm: "box-border h-3 px-2 py-0", default: "box-border h-4 px-2 py-0", lg: "box-border h-5 px-2 py-0", } as const; type InputSize = keyof typeof inputSizeClassName; function Input({ className, size = "default", ...props }: Omit<React.ComponentProps<"input">, "size"> & { size?: InputSize; }) { return ( <input data-slot="input" data-size={size} className={cn(inputSizeClassName[size], className)} {...props} /> ); } export { Input }; export type { InputSize }; ``` </Step> <Step> Copy and paste the separator component into your `components/ui/Separator.tsx` file. ```tsx "use client" import as React from "react" import {Separator as SeparatorPrimitive} from "radix-ui" import { cn } from "@/utils/class-names" function Separator({ className, orientation = "horizontal", decorative = true, ...props }: React.ComponentProps<typeof SeparatorPrimitive.Root>) { return ( <SeparatorPrimitive.Root data-slot="separator" decorative={decorative} orientation={orientation} className={cn( "bg-gray-a6 shrink-0 data-[orientation=horizontal]:h-px data-[orientation=horizontal]:w-full data-[orientation=vertical]:h-full data-[orientation=vertical]:w-px", className )} {...props} /> ) } export { Separator } ``` </Step> <Step> Copy and paste the sheet component into your `components/ui/Sheet.tsx` file. ```tsx "use client"; import * as React from "react"; import { Dialog as SheetPrimitive } from "radix-ui"; import { Cross2Icon } from "@radix-ui/react-icons" import { cn } from "@/utils/class-names"; import Button from "@/components/ui/Button"; function Sheet({ ...props }: React.ComponentProps<typeof SheetPrimitive.Root>) { return <SheetPrimitive.Root data-slot="sheet" {...props} />; } function SheetTrigger({ ...props }: React.ComponentProps<typeof SheetPrimitive.Trigger>) { return <SheetPrimitive.Trigger data-slot="sheet-trigger" {...props} />; } function SheetClose({ ...props }: React.ComponentProps<typeof SheetPrimitive.Close>) { return <SheetPrimitive.Close data-slot="sheet-close" {...props} />; } function SheetPortal({ ...props }: React.ComponentProps<typeof SheetPrimitive.Portal>) { return <SheetPrimitive.Portal data-slot="sheet-portal" {...props} />; } function SheetOverlay({ className, ...props }: React.ComponentProps<typeof SheetPrimitive.Overlay>) { return ( <SheetPrimitive.Overlay data-slot="sheet-overlay" className={cn( "aura-overlay z-50", className )} {...props} /> ); } function SheetContent({ className, children, side = "right", ...props }: React.ComponentProps<typeof SheetPrimitive.Content> & { side?: "top" | "right" | "bottom" | "left"; }) { return ( <SheetPortal> <SheetOverlay /> <SheetPrimitive.Content data-slot="sheet-content" className={cn( "bg-gray-1 fixed z-50 flex flex-col gap-1 shadow-lg", side === "right" && "data-[state=open]:animate-sheet-right-open data-[state=closed]:animate-sheet-right-closed inset-y-0 right-0 h-full w-3/4 border-l sm:max-w-sm border-gray-a6", side === "left" && "data-[state=open]:animate-sheet-left-open data-[state=closed]:animate-sheet-left-closed inset-y-0 left-0 h-full w-3/4 border-r sm:max-w-sm border-gray-a6", side === "top" && "data-[state=open]:animate-sheet-top-open data-[state=closed]:animate-sheet-top-closed inset-x-0 top-0 h-auto border-b border-gray-a6", side === "bottom" && "data-[state=open]:animate-sheet-bottom-open data-[state=closed]:animate-sheet-bottom-closed inset-x-0 bottom-0 h-auto border-t border-gray-a6", className )} {...props} > {children} <SheetPrimitive.Close className=" absolute top-0.5 right-0.5" asChild> <Button mode="link"> <Cross2Icon className="icon" /> <span className="sr-only">Close</span> </Button> </SheetPrimitive.Close> </SheetPrimitive.Content> </SheetPortal> ); } function SheetHeader({ className, ...props }: React.ComponentProps<"div">) { return ( <div data-slot="sheet-header" className={cn("flex flex-col gap-1.5 p-2", className)} {...props} /> ); } function SheetFooter({ className, ...props }: React.ComponentProps<"div">) { return ( <div data-slot="sheet-footer" className={cn("mt-auto flex flex-col gap-1 p-2", className)} {...props} /> ); } function SheetTitle({ className, ...props }: React.ComponentProps<typeof SheetPrimitive.Title>) { return ( <SheetPrimitive.Title data-slot="sheet-title" className={cn("text-gray-12 font-semibold", className)} {...props} /> ); } function SheetDescription({ className, ...props }: React.ComponentProps<typeof SheetPrimitive.Description>) { return ( <SheetPrimitive.Description data-slot="sheet-description" className={cn("text-gray-11 text-sm", className)} {...props} /> ); } export { Sheet, SheetTrigger, SheetClose, SheetContent, SheetHeader, SheetFooter, SheetTitle, SheetDescription, }; ``` </Step> <Step> Copy and paste the skeleton component into your `components/ui/Skeleton.tsx` file. ```tsx import { cn } from "@/utils/class-names" /** Indeterminate loading shimmer: Tailwind `animate-pulse` is an allowed exception (infinite loop). / function Skeleton({ className, ...props }: React.ComponentProps<"div">) { return ( <div data-slot="skeleton" className={cn("bg-gray-a6 animate-pulse rounded-md", className)} {...props} /> ) } export { Skeleton } ``` </Step> <Step> Copy and paste the tooltip component into your `components/ui/Tooltip.tsx` file. ```tsx "use client" import as React from "react" import { Tooltip as TooltipPrimitive } from "radix-ui" import { cn } from "@/utils/class-names" function TooltipProvider({ delayDuration = 0, ...props }: React.ComponentProps<typeof TooltipPrimitive.Provider>) { return ( <TooltipPrimitive.Provider data-slot="tooltip-provider" delayDuration={delayDuration} {...props} /> ) } function Tooltip({ ...props }: React.ComponentProps<typeof TooltipPrimitive.Root>) { return ( <TooltipProvider> <TooltipPrimitive.Root data-slot="tooltip" {...props} /> </TooltipProvider> ) } function TooltipTrigger({ ...props }: React.ComponentProps<typeof TooltipPrimitive.Trigger>) { return <TooltipPrimitive.Trigger data-slot="tooltip-trigger" {...props} /> } function TooltipContent({ className, sideOffset = 0, children, ...props }: React.ComponentProps<typeof TooltipPrimitive.Content>) { return ( <TooltipPrimitive.Portal> <TooltipPrimitive.Content data-slot="tooltip-content" sideOffset={sideOffset} className={cn( "bg-gray-12 text-gray-1 z-50 w-fit origin-(--radix-tooltip-content-transform-origin) rounded-md px-1 py-0.5 text-sm text-balance data-[state=open]:animate-tooltip-show data-[state=closed]:animate-tooltip-hide", className )} {...props} > {children} <TooltipPrimitive.Arrow className="fill-gray-12" /> </TooltipPrimitive.Content> </TooltipPrimitive.Portal> ) } export { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider } ``` </Step> <Step> Copy and paste the use mobile hook into your `hooks/use-mobile.ts` file. ```ts import * as React from "react" const MOBILE_BREAKPOINT = 768 export function useIsMobile(breakpoint = MOBILE_BREAKPOINT) { const [isMobile, setIsMobile] = React.useState<boolean | undefined>(undefined) React.useEffect(() => { const mql = window.matchMedia(`(max-width: ${breakpoint - 1}px)`) const onChange = () => { setIsMobile(window.innerWidth < breakpoint) } mql.addEventListener("change", onChange) setIsMobile(window.innerWidth < breakpoint) return () => mql.removeEventListener("change", onChange) }, [breakpoint]) return !!isMobile } ``` </Step> <Step> Copy and paste the Sidebar component into your `components/ui/Sidebar.tsx` file. ```tsx "use client"; import * as React from "react"; import { Slot } from "@radix-ui/react-slot"; import { HamburgerMenuIcon } from "@radix-ui/react-icons" import { useIsMobile } from "@/hooks/use-mobile"; import { cn } from "@/utils/class-names"; import Button from "@/components/ui/Button"; import { Input } from "@/components/ui/Input"; import { Separator } from "@/components/ui/Separator"; import { Sheet, SheetContent, SheetDescription, SheetHeader, SheetTitle, } from "@/components/ui/Sheet"; import { Skeleton } from "@/components/ui/Skeleton"; import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, } from "@/components/ui/Tooltip"; const SIDEBAR_COOKIE_NAME = "sidebar_state"; const SIDEBAR_COOKIE_MAX_AGE = 60 * 60 * 24 * 7; const SIDEBAR_WIDTH = "16rem"; const SIDEBAR_WIDTH_MOBILE = "18rem"; const SIDEBAR_WIDTH_ICON = "3rem"; const SIDEBAR_KEYBOARD_SHORTCUT = "b"; type SidebarContextProps = { state: "expanded" | "collapsed"; open: boolean; setOpen: (open: boolean) => void; openMobile: boolean; setOpenMobile: (open: boolean) => void; isMobile: boolean; toggleSidebar: () => void; }; const SidebarContext = React.createContext<SidebarContextProps | null>(null); function useSidebar() { const context = React.useContext(SidebarContext); if (!context) { throw new Error("useSidebar must be used within a SidebarProvider."); } return context; } function SidebarProvider({ defaultOpen = true, open: openProp, onOpenChange: setOpenProp, className, style, children, ...props }: React.ComponentProps<"div"> & { defaultOpen?: boolean; open?: boolean; onOpenChange?: (open: boolean) => void; }) { const isMobile = useIsMobile(); const [openMobile, setOpenMobile] = React.useState(false); // This is the internal state of the sidebar. // We use openProp and setOpenProp for control from outside the component. const [_open, _setOpen] = React.useState(defaultOpen); const open = openProp ?? _open; const setOpen = React.useCallback( (value: boolean | ((value: boolean) => boolean)) => { const openState = typeof value === "function" ? value(open) : value; if (setOpenProp) { setOpenProp(openState); } else { _setOpen(openState); } // This sets the cookie to keep the sidebar state. document.cookie = `${SIDEBAR_COOKIE_NAME}=${openState}; path=/; max-age=${SIDEBAR_COOKIE_MAX_AGE}`; }, [setOpenProp, open] ); // Helper to toggle the sidebar. const toggleSidebar = React.useCallback(() => { return isMobile ? setOpenMobile((open) => !open) : setOpen((open) => !open); }, [isMobile, setOpen, setOpenMobile]); // Adds a keyboard shortcut to toggle the sidebar. React.useEffect(() => { const handleKeyDown = (event: KeyboardEvent) => { if ( event.key === SIDEBAR_KEYBOARD_SHORTCUT && (event.metaKey || event.ctrlKey) ) { event.preventDefault(); toggleSidebar(); } }; window.addEventListener("keydown", handleKeyDown); return () => window.removeEventListener("keydown", handleKeyDown); }, [toggleSidebar]); // We add a state so that we can do data-state="expanded" or "collapsed". // This makes it easier to style the sidebar with Tailwind classes. const state = open ? "expanded" : "collapsed"; const contextValue = React.useMemo<SidebarContextProps>( () => ({ state, open, setOpen, isMobile, openMobile, setOpenMobile, toggleSidebar, }), [state, open, setOpen, isMobile, openMobile, setOpenMobile, toggleSidebar] ); return ( <SidebarContext.Provider value={contextValue}> <TooltipProvider delayDuration={0}> <div data-slot="sidebar-wrapper" style={ { "--sidebar-width": SIDEBAR_WIDTH, "--sidebar-width-icon": SIDEBAR_WIDTH_ICON, ...style, } as React.CSSProperties } className={cn( "group/sidebar-wrapper flex min-h-svh w-full bg-gray-2", className )} {...props} > {children} </div> </TooltipProvider> </SidebarContext.Provider> ); } function Sidebar({ side = "left", variant = "sidebar", collapsible = "offcanvas", className, children, ...props }: React.ComponentProps<"div"> & { side?: "left" | "right"; variant?: "sidebar" | "floating" | "inset"; collapsible?: "offcanvas" | "icon" | "none"; }) { const { isMobile, state, openMobile, setOpenMobile } = useSidebar(); if (collapsible === "none") { return ( <div data-slot="sidebar" className={cn( "bg-gray-4 flex h-full w-(--sidebar-width) flex-col", className )} {...props} > {children} </div> ); } if (isMobile) { return ( <Sheet open={openMobile} onOpenChange={setOpenMobile} {...props}> <SheetContent data-sidebar="sidebar" data-slot="sidebar" data-mobile="true" className="bg-gray-2 text-gray-12 w-(--sidebar-width) p-0 [&>button]:hidden" style={ { "--sidebar-width": SIDEBAR_WIDTH_MOBILE, } as React.CSSProperties } side={side} > <SheetHeader className="sr-only"> <SheetTitle>Sidebar</SheetTitle> <SheetDescription>Displays the mobile sidebar.</SheetDescription> </SheetHeader> <div className="flex h-full w-full flex-col">{children}</div> </SheetContent> </Sheet> ); } return ( <div className="group peer text-gray-12 hidden md:block" data-state={state} data-collapsible={state === "collapsed" ? collapsible : ""} data-variant={variant} data-side={side} data-slot="sidebar" > {/* This is what handles the sidebar gap on desktop /} <div data-slot="sidebar-gap" className={cn( "relative w-(--sidebar-width) bg-transparent", "group-data-[collapsible=offcanvas]:w-0", "group-data-[side=right]:rotate-180", variant === "floating" || variant === "inset" ? "group-data-[collapsible=icon]:w-[calc(var(--sidebar-width-icon)+(--spacing(4)))]" : "group-data-[collapsible=icon]:w-(--sidebar-width-icon)" )} /> <div data-slot="sidebar-container" className={cn( "fixed inset-y-0 z-10 hidden h-svh w-(--sidebar-width) md:flex border-gray-a6", side === "left" ? "left-0 group-data-[collapsible=offcanvas]:left-[calc(var(--sidebar-width)-1)]" : "right-0 group-data-[collapsible=offcanvas]:right-[calc(var(--sidebar-width)-1)]", // Adjust the padding for floating and inset variants. variant === "floating" || variant === "inset" ? "p-2 group-data-[collapsible=icon]:w-[calc(var(--sidebar-width-icon)+(--spacing(4))+2px)]" : "group-data-[collapsible=icon]:w-(--sidebar-width-icon) group-data-[side=left]:border-r group-data-[side=right]:border-l", className )} {...props} > <div data-sidebar="sidebar" data-slot="sidebar-inner" className={cn( "bg-gray-2 flex h-full w-full flex-col", "group-data-[variant=floating]:rounded-lg group-data-[variant=floating]:border group-data-[variant=floating]:border-gray-6 group-data-[variant=floating]:shadow-sm", "group-data-[collapsible=icon]:p-0.5" )} > {children} </div> </div> </div> ); } function SidebarTrigger({ className, onClick, ...props }: React.ComponentProps<typeof Button>) { const { toggleSidebar } = useSidebar(); return ( <Button data-sidebar="trigger" data-slot="sidebar-trigger" mode="link" className={cn( "inline-flex size-2.5 shrink-0 items-center justify-center rounded-md p-0 text-gray-12 hover:bg-gray-4 hover:text-gray-12 focus-visible:ring-2 focus-visible:ring-gray-8", className )} onClick={(event) => { onClick?.(event); toggleSidebar(); }} {...props} > <HamburgerMenuIcon className="icon" aria-hidden /> <span className="sr-only">Toggle Sidebar</span> </Button> ); } function SidebarRail({ className, ...props }: React.ComponentProps<"button">) { const { toggleSidebar } = useSidebar(); return ( <button data-sidebar="rail" data-slot="sidebar-rail" aria-label="Toggle Sidebar" tabIndex={-1} onClick={toggleSidebar} title="Toggle Sidebar" className={cn( "hover:after:bg-gray-a2 absolute inset-y-0 z-20 hidden w-1.5 -translate-x-1/2 group-data-[side=left]:-right-1.5 group-data-[side=right]:left-0 after:absolute after:inset-y-0 after:left-1/2 after:w-px sm:flex", "in-data-[side=left]:cursor-w-resize in-data-[side=right]:cursor-e-resize", "[[data-side=left][data-state=collapsed]_&]:cursor-e-resize [[data-side=right][data-state=collapsed]_&]:cursor-w-resize", "hover:group-data-[collapsible=offcanvas]:bg-gray-2 group-data-[collapsible=offcanvas]:translate-x-0 group-data-[collapsible=offcanvas]:after:left-full", "[[data-side=left][data-collapsible=offcanvas]_&]:-right-1", "[[data-side=right][data-collapsible=offcanvas]_&]:-left-1", className )} {...props} /> ); } function SidebarInset({ className, ...props }: React.ComponentProps<"main">) { return ( <main data-slot="sidebar-inset" className={cn( "bg-gray-1 relative flex w-full flex-1 flex-col", "md:peer-data-[variant=inset]:m-2 md:peer-data-[variant=inset]:ml-0 md:peer-data-[variant=inset]:rounded-xl md:peer-data-[variant=inset]:shadow-sm md:peer-data-[variant=inset]:peer-data-[state=collapsed]:ml-2", className )} {...props} /> ); } function SidebarInput({ className, ...props }: React.ComponentProps<typeof Input>) { return ( <Input data-slot="sidebar-input" data-sidebar="input" className={cn("bg-gray-1 h-2.5 w-full shadow-none", className)} {...props} /> ); } function SidebarHeader({ className, ...props }: React.ComponentProps<"div">) { return ( <div data-slot="sidebar-header" data-sidebar="header" className={cn( "flex flex-col gap-2 p-0.5", "group-data-[collapsible=icon]:gap-1 group-data-[collapsible=icon]:p-0", className )} {...props} /> ); } function SidebarFooter({ className, ...props }: React.ComponentProps<"div">) { return ( <div data-slot="sidebar-footer" data-sidebar="footer" className={cn( "flex flex-col gap-2 p-0.5", "group-data-[collapsible=icon]:gap-1 group-data-[collapsible=icon]:p-1", className )} {...props} /> ); } function SidebarSeparator({ className, ...props }: React.ComponentProps<typeof Separator>) { return ( <Separator data-slot="sidebar-separator" data-sidebar="separator" className={cn("bg-gray-6 mx-0.5 w-auto", className)} {...props} /> ); } function SidebarContent({ className, ...props }: React.ComponentProps<"div">) { return ( <div data-slot="sidebar-content" data-sidebar="content" className={cn( "no-scrollbar flex min-h-0 flex-1 flex-col gap-0 overflow-auto group-data-[collapsible=icon]:overflow-hidden group-data-[collapsible=icon]:gap-1", className )} {...props} /> ); } function SidebarGroup({ className, ...props }: React.ComponentProps<"div">) { return ( <div data-slot="sidebar-group" data-sidebar="group" className={cn( "relative flex w-full min-w-0 flex-col px-2 py-1 group-data-[collapsible=icon]:p-0", className )} {...props} /> ); } function SidebarGroupLabel({ className, asChild = false, ...props }: React.ComponentProps<"div"> & { asChild?: boolean }) { const Comp = asChild ? Slot : "div"; return ( <Comp data-slot="sidebar-group-label" data-sidebar="group-label" className={cn( "text-gray-a11 ring-gray-8 flex h-2.5 shrink-0 items-center rounded-md px-2 text-xs font-medium outline-hidden focus-visible:ring-2 pl-0", "group-data-[collapsible=icon]:-mt-2.5 group-data-[collapsible=icon]:opacity-0", "[&>svg]:size-1.5 [&>svg]:shrink-0", className )} {...props} /> ); } function SidebarGroupAction({ className, asChild = false, ...props }: React.ComponentProps<"button"> & { asChild?: boolean }) { const Comp = asChild ? Slot : "button"; return ( <Comp data-slot="sidebar-group-action" data-sidebar="group-action" className={cn( "text-gray-12 ring-gray-8 hover:bg-gray-4 hover:text-gray-12 absolute top-3.5 right-3 flex aspect-square w-2 items-center justify-center rounded-md p-0 outline-hidden focus-visible:ring-2 [&>svg]:shrink-0", // Increases the hit area of the button on mobile. "after:absolute after:-inset-2 md:after:hidden", "group-data-[collapsible=icon]:hidden", className )} {...props} /> ); } function SidebarGroupContent({ className, ...props }: React.ComponentProps<"div">) { return ( <div data-slot="sidebar-group-content" data-sidebar="group-content" className={cn("w-full text-sm", className)} {...props} /> ); } function SidebarMenu({ className, ...props }: React.ComponentProps<"ul">) { return ( <ul data-slot="sidebar-menu" data-sidebar="menu" className={cn("flex w-full min-w-0 flex-col gap-0", className)} {...props} /> ); } function SidebarMenuItem({ className, ...props }: React.ComponentProps<"li">) { return ( <li data-slot="sidebar-menu-item" data-sidebar="menu-item" className={cn("group/menu-item relative", className)} {...props} /> ); } function SidebarMenuButton({ asChild = false, isActive = false, size = "default", tooltip, className, ...props }: React.ComponentProps<"button"> & { asChild?: boolean; isActive?: boolean; size?: "default" | "sm" | "lg"; tooltip?: string | React.ComponentProps<typeof TooltipContent>; }) { const Comp = asChild ? Slot : "button"; const { isMobile, state } = useSidebar(); const button = ( <Comp data-slot="sidebar-menu-button" data-sidebar="menu-button" data-size={size} data-active={isActive} type={Comp === "button" ? "button" : undefined} className={cn( "ring-gray-8 outline-hidden flex w-full items-center gap-2 overflow-hidden rounded-md p-0.5 text-left", "hover:bg-gray-4 hover:text-gray-12 focus-visible:ring-2 active:bg-gray-5 active:text-gray-12", "disabled:pointer-events-none disabled:opacity-50 aria-disabled:pointer-events-none aria-disabled:opacity-50", "data-[active=true]:bg-gray-4 data-[active=true]:font-medium data-[active=true]:text-gray-12", "group-data-[collapsible=icon]:size-3! group-data-[collapsible=icon]:p-1! group-data-[collapsible=icon]:justify-center group-data-[collapsible=icon]:w-3!", "group-data-[collapsible=icon]:[&>svg]:size-1", "group-data-[collapsible=icon]:[&>span]:hidden", "group-has-data-[sidebar=menu-action]/menu-item:pr-2.5", "[&>svg]:size-1.5 [&>svg]:shrink-0 [&>span:last-child]:truncate", size === "lg" && "h-3.5 text-sm", size === "default" && "h-2.5 text-sm", size === "sm" && "h-2 text-xs", isActive && "bg-gray-4 font-medium text-gray-12", className )} {...props} /> ); if (!tooltip) { return button; } if (typeof tooltip === "string") { tooltip = { children: tooltip, }; } return ( <Tooltip> <TooltipTrigger asChild>{button}</TooltipTrigger> <TooltipContent side="right" align="center" hidden={state !== "collapsed" || isMobile} {...tooltip} /> </Tooltip> ); } function SidebarMenuAction({ className, asChild = false, showOnHover = false, ...props }: React.ComponentProps<"button"> & { asChild?: boolean; showOnHover?: boolean; }) { const Comp = asChild ? Slot : "button"; return ( <Comp data-slot="sidebar-menu-action" data-sidebar="menu-action" className={cn( "text-gray-12 ring-gray-8 hover:bg-gray-4 hover:text-gray-12 peer-hover/menu-button:text-gray-12 absolute right-1 top-1/2 flex aspect-square w-2 -translate-y-1/2 items-center justify-center rounded-md p-0 outline-hidden focus-visible:ring-2 [&>svg]:shrink-0", // Increases the hit area of the button on mobile. "after:absolute after:-inset-2 md:after:hidden", "group-data-[collapsible=icon]:hidden", showOnHover && "peer-data-[active=true]/menu-button:text-gray-12 group-focus-within/menu-item:opacity-100 group-hover/menu-item:opacity-100 data-[state=open]:opacity-100 md:opacity-0", className )} {...props} /> ); } function SidebarMenuBadge({ className, ...props }: React.ComponentProps<"div">) { return ( <div data-slot="sidebar-menu-badge" data-sidebar="menu-badge" className={cn( "text-gray-12 pointer-events-none absolute right-1 flex h-2 min-w-2 items-center justify-center rounded-md px-1 text-xs font-medium tabular-nums select-none", "peer-hover/menu-button:text-gray-12 peer-data-[active=true]/menu-button:text-gray-12", "peer-data-[size=sm]/menu-button:top-1", "peer-data-[size=default]/menu-button:top-1.5", "peer-data-[size=lg]/menu-button:top-2.5", "group-data-[collapsible=icon]:hidden", className )} {...props} /> ); } function SidebarMenuSkeleton({ className, showIcon = false, ...props }: React.ComponentProps<"div"> & { showIcon?: boolean; }) { // Random width between 50 to 90%. const width = React.useMemo(() => { return `${Math.floor(Math.random() 40) + 50}%`; }, []); return ( <div data-slot="sidebar-menu-skeleton" data-sidebar="menu-skeleton" className={cn("flex h-2.5 items-center gap-2 rounded-md px-2", className)} {...props} > {showIcon && ( <Skeleton className="size-1.5 rounded-md" data-sidebar="menu-skeleton-icon" /> )} <Skeleton className="h-1.5 max-w-(--skeleton-width) flex-1" data-sidebar="menu-skeleton-text" style={ { "--skeleton-width": width, } as React.CSSProperties } /> </div> ); } function SidebarMenuSub({ className, ...props }: React.ComponentProps<"ul">) { return ( <ul data-slot="sidebar-menu-sub" data-sidebar="menu-sub" className={cn( "border-gray-6 mx-1 flex min-w-0 translate-x-px flex-col gap-1 border-l px-2.5 py-0.5", "group-data-[collapsible=icon]:hidden", className )} {...props} /> ); } function SidebarMenuSubItem({ className, ...props }: React.ComponentProps<"li">) { return ( <li data-slot="sidebar-menu-sub-item" data-sidebar="menu-sub-item" className={cn("group/menu-sub-item relative", className)} {...props} /> ); } function SidebarMenuSubButton({ asChild = false, isActive = false, size = "md", className, ...props }: React.ComponentProps<"a"> & { asChild?: boolean; isActive?: boolean; size?: "sm" | "md"; }) { const Comp = asChild ? Slot : "a"; return ( <Comp data-slot="sidebar-menu-sub-button" data-sidebar="menu-sub-button" data-size={size} data-active={isActive} className={cn( "flex min-w-0 -translate-x-px items-center gap-2 overflow-hidden rounded-md px-2 text-gray-12 ring-gray-8 outline-hidden", "hover:bg-gray-4 hover:text-gray-12 focus-visible:ring-2 active:bg-gray-5 active:text-gray-12", "disabled:pointer-events-none disabled:opacity-50 aria-disabled:pointer-events-none aria-disabled:opacity-50", "data-[active=true]:bg-gray-4 data-[active=true]:text-gray-12", "data-[size=md]:text-sm data-[size=md]:h-2.5 data-[size=sm]:text-xs data-[size=sm]:h-2", "[&>span:last-child]:truncate [&>svg]:size-1.5 [&>svg]:shrink-0 [&>svg]:text-gray-12", "group-data-[collapsible=icon]:hidden", isActive && "bg-gray-4 text-gray-12", className )} {...props} /> ); } export { Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupAction, SidebarGroupContent, SidebarGroupLabel, SidebarHeader, SidebarInput, SidebarInset, SidebarMenu, SidebarMenuAction, SidebarMenuBadge, SidebarMenuButton, SidebarMenuItem, SidebarMenuSkeleton, SidebarMenuSub, SidebarMenuSubButton, SidebarMenuSubItem, SidebarProvider, SidebarRail, SidebarSeparator, SidebarTrigger, useSidebar, }; ``` </Step> </Steps> # Signature Pad (/docs/components/signature-pad) ## Preview [#preview] <ComponentPreview name="signature-pad-demo" description="A component that allows the user to sign a document using a pen."> ```tsx import { useRef, useState } from "react"; import type { ComponentRef } from "react"; import SignaturePad from "@/components/ui/SignaturePad"; import { Button } from "@/components/ui/Button"; import { CheckIcon, SymbolIcon } from "@radix-ui/react-icons"; export function SignaturePadDemo() { return <SignaturePad />; } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/signature-pad ``` ### Manual [#manual] <Steps> <Step> Install the following dependencies: ```bash pnpm install @radix-ui/react-icons class-variance-authority ``` </Step> <Step> Copy and paste the button component into your `components/ui/Button.tsx` file. ```tsx /** * @description Displays a button or a component that looks like a button. / import as React from "react"; import { Slot } from "@radix-ui/react-slot"; import { cva, type VariantProps } from "class-variance-authority"; import { cn } from "@/utils/class-names"; const buttonVariants = cva("button", { variants: { variant: { default: "button-fill", fill: "button-fill", pill: "button-pill border border-gray-6 text-gray-11 bg-gray-2 hover:bg-gray-3", link: "button-link", menu: "button-menu", }, size: { default: "h-4", xs: "h-2.5", sm: "h-3", md: "h-4", lg: "h-5", xl: "h-6", icon: "w-3 h-3 p-0", "icon-md": "w-4 h-4 p-0", }, }, defaultVariants: { variant: "default", size: "default", }, }); interface ButtonProps extends React.ComponentProps<"button">, VariantProps<typeof buttonVariants> { asChild?: boolean; isDisabled?: boolean; isLoading?: boolean; isLoadingText?: string | React.ReactNode; mode?: VariantProps<typeof buttonVariants>["variant"]; label?: string | React.ReactNode; } const Button = React.forwardRef<HTMLButtonElement, ButtonProps>( (props: ButtonProps, ref) => { const { className, variant, mode, size, asChild = false, isDisabled, isLoading, isLoadingText, children, label, ...rest } = props; const Comp = asChild ? Slot : "button"; const disabled = isDisabled || isLoading || props.disabled; const effectiveVariant = variant ?? mode; return ( <Comp data-slot="button" className={cn( buttonVariants({ variant: effectiveVariant, size, className }), disabled && "opacity-50 cursor-not-allowed" )} ref={ref} disabled={disabled} {...rest} > {asChild ? ( children ) : ( <> {isLoading && isLoadingText ? isLoadingText : <>{label}{children}</>} </> )} </Comp> ); } ); Button.displayName = "Button"; export { Button, buttonVariants }; export type { ButtonProps }; export default Button; ``` </Step> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the SignaturePad component into your `components/ui/SignaturePad.tsx` file. ```tsx "use client"; import React, { type MouseEvent, type TouchEvent, useEffect, useImperativeHandle, useRef, useState, } from "react"; import { cva, type VariantProps } from "class-variance-authority"; import { SymbolIcon, CheckIcon } from "@radix-ui/react-icons"; import { Button } from "@/components/ui/Button"; import { cn } from "@/utils/class-names"; const signaturePadVariants = cva("touch-none cursor-pencil", { variants: { variant: { default: "border border-gray-6 bg-gray-a2", ghost: "border-none bg-gray-a2", outline: "border border-gray-a6 bg-gray-1", }, size: { default: "w-full h-[195px]", sm: "w-full h-[149.5px]", md: "w-full h-[247px]", lg: "w-full h-[299px]", }, }, defaultVariants: { variant: "default", size: "default", }, }); export interface SignaturePadProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange">, VariantProps<typeof signaturePadVariants> { /** @public (optional) - Tailwind color utility class for the pen color (e.g. "text-black", "text-primary-500") */ penColor?: string; /** @public (optional) - Line width in pixels */ lineWidth?: number; /** @public (optional) - Whether to show the buttons */ showButtons?: boolean; /** @public (optional) - The icon to display for the save button */ saveButtonIcon?: React.ReactNode; /** @public (optional) - The icon to display for the clear button */ clearButtonIcon?: React.ReactNode; /** @public (optional) - Callback function to be called when the signature is saved */ onSave?: (signature: Base64URLString) => void; /** @public (optional) - Callback function to be called when the signature is changed / onChange?: (signature: Base64URLString | null) => void; } interface SignaturePadRef { clear: () => void; save: () => void; toDataURL: () => Base64URLString | null; isEmpty: () => boolean; getCanvas: () => HTMLCanvasElement | null; } const SignaturePad = React.forwardRef<SignaturePadRef, SignaturePadProps>( ( { penColor = "var(--accent-9)", lineWidth = 4, showButtons = true, saveButtonIcon, clearButtonIcon, variant, size, className, onSave, onChange, ...props }, ref ) => { const [isDrawing, setIsDrawing] = useState(false); const [isEmpty, setIsEmpty] = useState(true); const pointsRef = useRef<{ x: number; y: number }[]>([]); const canvasRef = useRef<HTMLCanvasElement>(null); const ctxRef = useRef<CanvasRenderingContext2D | null>(null); // Helper function to resolve CSS variables to actual color values const resolveColor = (color: string): string => { if (!color.startsWith("var(")) { return color; } // Extract the variable name from var(--variable-name) const match = color.match(/var$(--[^)]+)$/); if (!match) return color; const variableName = match[1]; const canvas = canvasRef.current; if (!canvas) return color; // Get the computed style from the canvas element const computedStyle = getComputedStyle(canvas); const resolvedColor = computedStyle.getPropertyValue(variableName).trim(); // If the variable is not found or empty, return the original return resolvedColor || color; }; // Expose the clear, save, toDataURL, isEmpty, and getCanvas methods to the parent component useImperativeHandle(ref, () => ({ clear: handleClear, save: handleSave, toDataURL: () => { const canvas = canvasRef.current; if (!canvas) return null; return canvas.toDataURL("image/png") as Base64URLString; }, isEmpty: () => isEmpty, getCanvas: () => canvasRef.current, })); // Update the canvas size for High DPI displays useEffect(() => { const canvas = canvasRef.current; if (!canvas) return; const updateCanvasSize = () => { const rect = canvas.getBoundingClientRect(); const ratio = window.devicePixelRatio || 1; canvas.width = rect.width ratio; canvas.height = rect.height * ratio; canvas.style.width = `${rect.width}px`; canvas.style.height = `${rect.height}px`; const ctx = canvas.getContext("2d"); if (ctx) { ctx.scale(ratio, ratio); ctx.lineCap = "round"; ctx.lineJoin = "round"; ctx.strokeStyle = resolveColor(penColor); ctx.lineWidth = lineWidth; ctx.imageSmoothingEnabled = true; ctx.imageSmoothingQuality = "high"; ctx.globalCompositeOperation = "source-over"; ctxRef.current = ctx; } }; updateCanvasSize(); window.addEventListener("resize", updateCanvasSize); return () => { window.removeEventListener("resize", updateCanvasSize); }; }, [penColor, lineWidth]); // Get the pointer position on the canvas const getPointerPosition = (e: MouseEvent | TouchEvent) => { const canvas = canvasRef.current; if (!canvas) return null; const rect = canvas.getBoundingClientRect(); if ("touches" in e) { return { x: e.touches[0].clientX - rect.left, y: e.touches[0].clientY - rect.top, }; } return { x: e.clientX - rect.left, y: e.clientY - rect.top, }; }; // Start drawing on the canvas const startDrawing = (e: MouseEvent | TouchEvent) => { e.preventDefault(); const pointerPosition = getPointerPosition(e); if (!pointerPosition) return; setIsDrawing(true); pointsRef.current = [pointerPosition]; setIsEmpty(false); }; const draw = (e: MouseEvent | TouchEvent) => { e.preventDefault(); if (!isDrawing) return; const canvas = canvasRef.current; let ctx = ctxRef.current; if (!ctx) ctx = canvas?.getContext("2d") as CanvasRenderingContext2D; // Ensure strokeStyle is set with resolved color if (ctx) { ctx.strokeStyle = resolveColor(penColor); } const newPoint = getPointerPosition(e); if (ctx && newPoint) { const updated = [...pointsRef.current, newPoint]; if (updated.length < 2) { pointsRef.current = updated; return; } if (updated.length === 2) { ctx.beginPath(); ctx.moveTo(updated[0].x, updated[0].y); ctx.lineTo(updated[1].x, updated[1].y); ctx.stroke(); pointsRef.current = updated; return; } const previous = updated[updated.length - 3]; const current = updated[updated.length - 2]; const next = updated[updated.length - 1]; const cp1x = (previous.x + current.x) / 2; const cp1y = (previous.y + current.y) / 2; const cp2x = (current.x + next.x) / 2; const cp2y = (current.y + next.y) / 2; ctx.beginPath(); ctx.moveTo(cp1x, cp1y); ctx.quadraticCurveTo(current.x, current.y, cp2x, cp2y); ctx.stroke(); pointsRef.current = updated.slice(-3); return; } }; const stopDrawing = () => { setIsDrawing(false); pointsRef.current = []; if (isDrawing) { onChange?.( canvasRef.current?.toDataURL("image/png") as Base64URLString ); } }; const handleClear = () => { const canvas = canvasRef.current; if (!canvas) return; const ctx = canvas.getContext("2d"); if (!ctx) return; ctx.clearRect(0, 0, canvas.width, canvas.height); setIsEmpty(true); onChange?.(null); }; const handleSave = () => { const canvas = canvasRef.current; if (!canvas && isEmpty) return; const dataURL = canvas?.toDataURL("image/png"); onSave?.(dataURL as Base64URLString); }; return ( <div className={cn("w-full relative", className)} {...props}> <canvas ref={canvasRef} className={cn( "rounded-lg cursor-pencil", signaturePadVariants({ variant, size }) )} onMouseDown={startDrawing} onMouseMove={draw} onMouseUp={stopDrawing} onMouseLeave={stopDrawing} onTouchStart={startDrawing} onTouchMove={draw} onTouchEnd={stopDrawing} /> {showButtons && ( <div className="absolute bottom-1 right-1 flex gap-0.5"> <Button variant="pill" size="sm" onClick={handleClear} className="rounded-full" type="button" > {clearButtonIcon || <SymbolIcon />} </Button> <Button variant="pill" size="sm" onClick={handleSave} className="rounded-full" type="button" > {saveButtonIcon || <CheckIcon />} </Button> </div> )} </div> ); } ); export default SignaturePad; ``` </Step> </Steps> ## Usage [#usage] ### WithoutButtons [#withoutbuttons] ```tsx export const WithoutButtons = () => <SignaturePad showButtons={false} />; ``` ### Variants [#variants] ```tsx export const Variants = () => ( <div className="flex flex-col gap-4"> <div> <p className="text-sm font-medium mb-2">Default</p> <SignaturePad variant="default" /> </div> <div> <p className="text-sm font-medium mb-2">Ghost</p> <SignaturePad variant="ghost" /> </div> <div> <p className="text-sm font-medium mb-2">Outline</p> <SignaturePad variant="pill" /> </div> </div> ) ``` ### Sizes [#sizes] ```tsx export const Sizes = () => ( <div className="flex flex-col gap-4"> <div> <p className="text-sm font-medium mb-2">Small</p> <SignaturePad size="sm" /> </div> <div> <p className="text-sm font-medium mb-2">Default</p> <SignaturePad size="default" /> </div> <div> <p className="text-sm font-medium mb-2">Medium</p> <SignaturePad size="md" /> </div> <div> <p className="text-sm font-medium mb-2">Large</p> <SignaturePad size="lg" /> </div> </div> ) ``` ### CustomPenColor [#custompencolor] ```tsx export const CustomPenColor = () => ( <div className="flex flex-col gap-4"> <div> <p className="text-sm font-medium mb-2">Gray 9</p> <SignaturePad penColor="var(--gray-9)" /> </div> <div> <p className="text-sm font-medium mb-2">Accent 9</p> <SignaturePad penColor="var(--accent-9)" /> </div> </div> ) ``` ### CustomLineWidth [#customlinewidth] ```tsx export const CustomLineWidth = () => ( <div className="flex flex-col gap-4"> <div> <p className="text-sm font-medium mb-2">Thin (2px)</p> <SignaturePad lineWidth={2} /> </div> <div> <p className="text-sm font-medium mb-2">Default (4px)</p> <SignaturePad lineWidth={4} /> </div> <div> <p className="text-sm font-medium mb-2">Thick (6px)</p> <SignaturePad lineWidth={6} /> </div> <div> <p className="text-sm font-medium mb-2">Very Thick (8px)</p> <SignaturePad lineWidth={8} /> </div> </div> ) ``` ### WithCustomIcons [#withcustomicons] ```tsx export const WithCustomIcons = () => ( <SignaturePad saveButtonIcon={<CheckIcon />} clearButtonIcon={<SymbolIcon />} /> ) ``` ### WithOnSave [#withonsave] ```tsx export const WithOnSave = () => { const [savedSignature, setSavedSignature] = useState<string | null>(null); return ( <div className="flex flex-col gap-4"> <SignaturePad onSave={(signature) => { setSavedSignature(signature); console.log("Signature saved:", signature); }} /> {savedSignature && ( <div className="mt-4"> <p className="text-sm font-medium mb-2">Saved Signature:</p> <img src={savedSignature} alt="Saved signature" className="border border-gray-6 rounded-lg" /> </div> )} </div> ); }; ``` ### WithOnChange [#withonchange] ```tsx export const WithOnChange = () => { const [hasSignature, setHasSignature] = useState(false); return ( <div className="flex flex-col gap-4"> <SignaturePad onChange={(signature) => { setHasSignature(signature !== null); console.log("Signature changed:", signature ? "Has signature" : "Empty"); }} /> <div className="text-sm"> Status: {hasSignature ? "✓ Has signature" : "Empty"} </div> </div> ); }; ``` ### WithRefMethods [#withrefmethods] ```tsx export const WithRefMethods = () => { const signaturePadRef = useRef<ComponentRef<typeof SignaturePad>>(null); const [signatureData, setSignatureData] = useState<string | null>(null); const [isEmpty, setIsEmpty] = useState(true); const handleClear = () => { signaturePadRef.current?.clear(); setSignatureData(null); setIsEmpty(true); }; const handleSave = () => { signaturePadRef.current?.save(); const dataURL = signaturePadRef.current?.toDataURL(); if (dataURL) { setSignatureData(dataURL); } }; const handleCheckEmpty = () => { const empty = signaturePadRef.current?.isEmpty() ?? true; setIsEmpty(empty); }; return ( <div className="flex flex-col gap-4"> <SignaturePad ref={signaturePadRef} showButtons={false} /> <div className="flex gap-2"> <Button onClick={handleClear} variant="pill" size="sm"> Clear (via ref) </Button> <Button onClick={handleSave} variant="pill" size="sm"> Save (via ref) </Button> <Button onClick={handleCheckEmpty} variant="pill" size="sm"> Check Empty </Button> </div> <div className="text-sm"> Is Empty: {isEmpty ? "Yes" : "No"} </div> {signatureData && ( <div> <p className="text-sm font-medium mb-2">Saved Signature:</p> <img src={signatureData} alt="Saved signature" className="border border-gray-6 rounded-lg max-w-xs" /> </div> )} </div> ); }; ``` ### CombinedExample [#combinedexample] ```tsx export const CombinedExample = () => { const [signature, setSignature] = useState<string | null>(null); return ( <div className="flex flex-col gap-4 max-w-md"> <div> <p className="text-sm font-medium mb-2">Sign below:</p> <SignaturePad variant="pill" size="md" penColor="hsl(var(--foreground))" lineWidth={3} onSave={(dataURL) => { setSignature(dataURL); alert("Signature saved!"); }} onChange={(dataURL) => { console.log("Signature changed"); }} /> </div> {signature && ( <div> <p className="text-sm font-medium mb-2">Your signature:</p> <img src={signature} alt="Your signature" className="border border-gray-6 rounded-lg" /> </div> )} </div> ); }; ``` # Skeleton (/docs/components/skeleton) ## Preview [#preview] <ComponentPreview name="skeleton-demo" description="A loading placeholder with pulse animation, typically used for content that is being fetched."> ```tsx import { Skeleton } from "@/components/ui/Skeleton"; export function SkeletonDemo() { return ( <div className="flex flex-col gap-2 w-full max-w-md"> <Skeleton className="h-4 w-full" /> <Skeleton className="h-4 w-3/4" /> <Skeleton className="h-4 w-1/2" /> </div> ); } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/skeleton ``` ### Manual [#manual] <Steps> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the Skeleton component into your `components/ui/Skeleton.tsx` file. ```tsx import { cn } from "@/utils/class-names" /** Indeterminate loading shimmer: Tailwind `animate-pulse` is an allowed exception (infinite loop). */ function Skeleton({ className, ...props }: React.ComponentProps<"div">) { return ( <div data-slot="skeleton" className={cn("bg-gray-a6 animate-pulse rounded-md", className)} {...props} /> ) } export { Skeleton } ``` </Step> </Steps> # Slider (/docs/components/slider) ## Preview [#preview] <ComponentPreview name="slider-demo" description="An input where the user selects a value from within a given range."> ```tsx import { Slider } from "@/components/ui/Slider"; export function SliderDemo() { return ( <div className="p-4"> <Slider defaultValue={[50]} max={100} step={1} /> </div> ) ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/slider ``` ### Manual [#manual] <Steps> <Step> Install the following dependencies: ```bash pnpm install radix-ui ``` </Step> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the Slider component into your `components/ui/Slider.tsx` file. ```tsx "use client" /** * @description An input where the user selects a value from within a given range. / import as React from "react" import { Slider as SliderPrimitive } from "radix-ui" import { cn } from "@/utils/class-names" const Slider = React.forwardRef< React.ElementRef<typeof SliderPrimitive.Root>, React.ComponentPropsWithoutRef<typeof SliderPrimitive.Root> >(({ className, ...props }, ref) => ( <SliderPrimitive.Root ref={ref} className={cn( "relative flex w-full touch-none select-none items-center", className )} {...props} > <SliderPrimitive.Track className="relative h-0.5 w-full grow overflow-hidden rounded-full bg-gray-3"> <SliderPrimitive.Range className="absolute h-full bg-accent-9" /> </SliderPrimitive.Track> <SliderPrimitive.Thumb className="block size-1.5 rounded-full border border-gray-6 bg-gray-1 ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50" /> </SliderPrimitive.Root> )) Slider.displayName = SliderPrimitive.Root.displayName export { Slider } ``` </Step> </Steps> ## Usage [#usage] ### Disabled [#disabled] ```tsx export const Disabled = () => ( <div className="p-4"> <Slider defaultValue={[25]} max={100} step={1} disabled /> </div> ) ``` ### WithSteps [#withsteps] ```tsx export const WithSteps = () => ( <div className="p-4"> <Slider defaultValue={[33]} max={100} step={33} /> </div> ) ``` # Snackbar (/docs/components/snackbar) ## Preview [#preview] <ComponentPreview name="snackbar-demo" description="A short message at the bottom of the screen with one optional action."> ```tsx import { Snackbar, SnackbarAction } from "@/components/ui/Snackbar"; export function SnackbarDemo() { return ( <Snackbar position="inline" action={<SnackbarAction>Undo</SnackbarAction>}> Message archived </Snackbar> ); } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/snackbar ``` ### Manual [#manual] <Steps> <Step> Install the following dependencies: ```bash pnpm install @radix-ui/react-icons ``` </Step> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the Snackbar component into your `components/ui/Snackbar.tsx` file. ```tsx "use client"; import * as React from "react"; import { Cross2Icon } from "@radix-ui/react-icons"; import { cn } from "@/utils/class-names"; type SnackbarProps = React.ComponentProps<"div"> & { open?: boolean; onOpenChange?: (open: boolean) => void; action?: React.ReactNode; position?: "fixed" | "inline"; }; function Snackbar({ className, open = true, onOpenChange, action, position = "fixed", children, ...props }: SnackbarProps) { if (!open) return null; return ( <div role="status" data-slot="snackbar" className={cn( "z-50 flex max-w-full items-center gap-1 rounded-sm bg-gray-12 px-1.5 py-1 text-gray-1 shadow-md", position === "fixed" ? "fixed inset-x-2 bottom-2 mx-auto w-fit" : "relative w-fit", className, )} {...props} > <p className="m-0">{children}</p> {action} {onOpenChange ? ( <button type="button" aria-label="Dismiss" className="inline-flex size-2 items-center justify-center rounded-sm text-gray-1 hover:bg-gray-a3 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent-8" onClick={() => onOpenChange(false)} > <Cross2Icon className="icon" /> </button> ) : null} </div> ); } function SnackbarAction({ className, ...props }: React.ComponentProps<"button">) { return ( <button type="button" data-slot="snackbar-action" className={cn( "font-medium text-accent-9 hover:text-accent-10 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent-8", className, )} {...props} /> ); } export { Snackbar, SnackbarAction }; ``` </Step> </Steps> # Sortable (/docs/components/sortable) ## Preview [#preview] <ComponentPreview name="sortable-demo" description="A sortable list of items."> ```tsx import { useState } from "react"; import { DragHandleDots2Icon } from "@radix-ui/react-icons"; import { Sortable, SortableContent, SortableItem, SortableItemHandle, SortableOverlay, } from "@/components/ui/Sortable"; export function SortableDemo() { const [items, setItems] = useState(["Item 1", "Item 2", "Item 3", "Item 4"]); return ( <Sortable value={items} onValueChange={setItems}> <SortableContent className="flex flex-col gap-1 w-full max-w-sm"> {items.map((item) => ( <SortableItem key={item} value={item} asHandle className="bg-gray-2 border border-gray-6 rounded-md p-1 text-gray-12" > {item} </SortableItem> ))} </SortableContent> </Sortable> ); } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/sortable ``` ### Manual [#manual] <Steps> <Step> Install the following dependencies: ```bash pnpm install @dnd-kit/core @dnd-kit/modifiers @dnd-kit/sortable @dnd-kit/utilities @radix-ui/react-slot ``` </Step> <Step> Copy and paste the Sortable component into your `components/ui/Sortable.tsx` file. ```tsx "use client"; import { type Announcements, closestCenter, closestCorners, DndContext, type DndContextProps, type DragEndEvent, type DraggableAttributes, type DraggableSyntheticListeners, DragOverlay, type DragStartEvent, type DropAnimation, defaultDropAnimationSideEffects, KeyboardSensor, MouseSensor, type ScreenReaderInstructions, TouchSensor, type UniqueIdentifier, useSensor, useSensors, } from "@dnd-kit/core"; import { restrictToHorizontalAxis, restrictToParentElement, restrictToVerticalAxis, } from "@dnd-kit/modifiers"; import { arrayMove, horizontalListSortingStrategy, SortableContext, type SortableContextProps, sortableKeyboardCoordinates, useSortable, verticalListSortingStrategy, } from "@dnd-kit/sortable"; import { CSS } from "@dnd-kit/utilities"; import { Slot } from "@radix-ui/react-slot"; import * as React from "react"; import * as ReactDOM from "react-dom"; import { useComposedRefs } from "../../utils/compose-refs"; import { cn } from "../../utils/class-names"; const orientationConfig = { vertical: { modifiers: [restrictToVerticalAxis, restrictToParentElement], strategy: verticalListSortingStrategy, collisionDetection: closestCenter, }, horizontal: { modifiers: [restrictToHorizontalAxis, restrictToParentElement], strategy: horizontalListSortingStrategy, collisionDetection: closestCenter, }, mixed: { modifiers: [restrictToParentElement], strategy: undefined, collisionDetection: closestCorners, }, }; const ROOT_NAME = "Sortable"; const CONTENT_NAME = "SortableContent"; const ITEM_NAME = "SortableItem"; const ITEM_HANDLE_NAME = "SortableItemHandle"; const OVERLAY_NAME = "SortableOverlay"; interface SortableRootContextValue<T> { id: string; items: UniqueIdentifier[]; modifiers: DndContextProps["modifiers"]; strategy: SortableContextProps["strategy"]; activeId: UniqueIdentifier | null; setActiveId: (id: UniqueIdentifier | null) => void; getItemValue: (item: T) => UniqueIdentifier; flatCursor: boolean; } const SortableRootContext = React.createContext<SortableRootContextValue<unknown> | null>(null); function useSortableContext(consumerName: string) { const context = React.useContext(SortableRootContext); if (!context) { throw new Error(`\`${consumerName}\` must be used within \`${ROOT_NAME}\``); } return context; } interface GetItemValue<T> { /** * Callback that returns a unique identifier for each sortable item. Required for array of objects. * @example getItemValue={(item) => item.id} */ getItemValue: (item: T) => UniqueIdentifier; } type SortableProps<T> = DndContextProps & (T extends object ? GetItemValue<T> : Partial<GetItemValue<T>>) & { value: T[]; onValueChange?: (items: T[]) => void; onMove?: ( event: DragEndEvent & { activeIndex: number; overIndex: number }, ) => void; strategy?: SortableContextProps["strategy"]; orientation?: "vertical" | "horizontal" | "mixed"; flatCursor?: boolean; }; function Sortable<T>(props: SortableProps<T>) { const { value, onValueChange, collisionDetection, modifiers, strategy, onMove, orientation = "vertical", flatCursor = false, getItemValue: getItemValueProp, accessibility, ...sortableProps } = props; const id = React.useId(); const [activeId, setActiveId] = React.useState<UniqueIdentifier | null>(null); const sensors = useSensors( useSensor(MouseSensor), useSensor(TouchSensor), useSensor(KeyboardSensor, { coordinateGetter: sortableKeyboardCoordinates, }), ); const config = React.useMemo( () => orientationConfig[orientation], [orientation], ); const getItemValue = React.useCallback( (item: T): UniqueIdentifier => { if (typeof item === "object" && !getItemValueProp) { throw new Error( "`getItemValue` is required when using array of objects", ); } return getItemValueProp ? getItemValueProp(item) : (item as UniqueIdentifier); }, [getItemValueProp], ); const items = React.useMemo(() => { return value.map((item) => getItemValue(item)); }, [value, getItemValue]); const onDragStart = React.useCallback( (event: DragStartEvent) => { sortableProps.onDragStart?.(event); if (event.activatorEvent.defaultPrevented) return; setActiveId(event.active.id); }, [sortableProps.onDragStart], ); const onDragEnd = React.useCallback( (event: DragEndEvent) => { sortableProps.onDragEnd?.(event); if (event.activatorEvent.defaultPrevented) return; const { active, over } = event; if (over && active.id !== over?.id) { const activeIndex = value.findIndex( (item) => getItemValue(item) === active.id, ); const overIndex = value.findIndex( (item) => getItemValue(item) === over.id, ); if (onMove) { onMove({ ...event, activeIndex, overIndex }); } else { onValueChange?.(arrayMove(value, activeIndex, overIndex)); } } setActiveId(null); }, [value, onValueChange, onMove, getItemValue, sortableProps.onDragEnd], ); const onDragCancel = React.useCallback( (event: DragEndEvent) => { sortableProps.onDragCancel?.(event); if (event.activatorEvent.defaultPrevented) return; setActiveId(null); }, [sortableProps.onDragCancel], ); const announcements: Announcements = React.useMemo( () => ({ onDragStart({ active }) { const activeValue = active.id.toString(); return `Grabbed sortable item "${activeValue}". Current position is ${active.data.current?.sortable.index + 1} of ${value.length}. Use arrow keys to move, space to drop.`; }, onDragOver({ active, over }) { if (over) { const overIndex = over.data.current?.sortable.index ?? 0; const activeIndex = active.data.current?.sortable.index ?? 0; const moveDirection = overIndex > activeIndex ? "down" : "up"; const activeValue = active.id.toString(); return `Sortable item "${activeValue}" moved ${moveDirection} to position ${overIndex + 1} of ${value.length}.`; } return "Sortable item is no longer over a droppable area. Press escape to cancel."; }, onDragEnd({ active, over }) { const activeValue = active.id.toString(); if (over) { const overIndex = over.data.current?.sortable.index ?? 0; return `Sortable item "${activeValue}" dropped at position ${overIndex + 1} of ${value.length}.`; } return `Sortable item "${activeValue}" dropped. No changes were made.`; }, onDragCancel({ active }) { const activeIndex = active.data.current?.sortable.index ?? 0; const activeValue = active.id.toString(); return `Sorting cancelled. Sortable item "${activeValue}" returned to position ${activeIndex + 1} of ${value.length}.`; }, onDragMove({ active, over }) { if (over) { const overIndex = over.data.current?.sortable.index ?? 0; const activeIndex = active.data.current?.sortable.index ?? 0; const moveDirection = overIndex > activeIndex ? "down" : "up"; const activeValue = active.id.toString(); return `Sortable item "${activeValue}" is moving ${moveDirection} to position ${overIndex + 1} of ${value.length}.`; } return "Sortable item is no longer over a droppable area. Press escape to cancel."; }, }), [value], ); const screenReaderInstructions: ScreenReaderInstructions = React.useMemo( () => ({ draggable: ` To pick up a sortable item, press space or enter. While dragging, use the ${orientation === "vertical" ? "up and down" : orientation === "horizontal" ? "left and right" : "arrow"} keys to move the item. Press space or enter again to drop the item in its new position, or press escape to cancel. `, }), [orientation], ); const contextValue = React.useMemo( () => ({ id, items, modifiers: modifiers ?? config.modifiers, strategy: strategy ?? config.strategy, activeId, setActiveId, getItemValue, flatCursor, }), [ id, items, modifiers, strategy, config.modifiers, config.strategy, activeId, getItemValue, flatCursor, ], ); return ( <SortableRootContext.Provider value={contextValue as SortableRootContextValue<unknown>} > <DndContext collisionDetection={collisionDetection ?? config.collisionDetection} modifiers={modifiers ?? config.modifiers} sensors={sensors} {...sortableProps} id={id} onDragStart={onDragStart} onDragEnd={onDragEnd} onDragCancel={onDragCancel} accessibility={{ announcements, screenReaderInstructions, ...accessibility, }} /> </SortableRootContext.Provider> ); } const SortableContentContext = React.createContext<boolean>(false); interface SortableContentProps extends React.ComponentProps<"div"> { strategy?: SortableContextProps["strategy"]; children: React.ReactNode; asChild?: boolean; withoutSlot?: boolean; } function SortableContent(props: SortableContentProps) { const { strategy: strategyProp, asChild, withoutSlot, children, ref, ...contentProps } = props; const context = useSortableContext(CONTENT_NAME); const ContentPrimitive = asChild ? Slot : "div"; return ( <SortableContentContext.Provider value={true}> <SortableContext items={context.items} strategy={strategyProp ?? context.strategy} > {withoutSlot ? ( children ) : ( <ContentPrimitive data-slot="sortable-content" {...contentProps} ref={ref} > {children} </ContentPrimitive> )} </SortableContext> </SortableContentContext.Provider> ); } interface SortableItemContextValue { id: string; attributes: DraggableAttributes; listeners: DraggableSyntheticListeners | undefined; setActivatorNodeRef: (node: HTMLElement | null) => void; isDragging?: boolean; disabled?: boolean; } const SortableItemContext = React.createContext<SortableItemContextValue | null>(null); function useSortableItemContext(consumerName: string) { const context = React.useContext(SortableItemContext); if (!context) { throw new Error(`\`${consumerName}\` must be used within \`${ITEM_NAME}\``); } return context; } interface SortableItemProps extends React.ComponentProps<"div"> { value: UniqueIdentifier; asHandle?: boolean; asChild?: boolean; disabled?: boolean; } function SortableItem(props: SortableItemProps) { const { value, style, asHandle, asChild, disabled, className, ref, ...itemProps } = props; const inSortableContent = React.useContext(SortableContentContext); const inSortableOverlay = React.useContext(SortableOverlayContext); if (!inSortableContent && !inSortableOverlay) { throw new Error( `\`${ITEM_NAME}\` must be used within \`${CONTENT_NAME}\` or \`${OVERLAY_NAME}\``, ); } if (value === "") { throw new Error(`\`${ITEM_NAME}\` value cannot be an empty string`); } const context = useSortableContext(ITEM_NAME); const id = React.useId(); const { attributes, listeners, setNodeRef, setActivatorNodeRef, transform, transition, isDragging, } = useSortable({ id: value, disabled }); const composedRef = useComposedRefs(ref, (node) => { if (disabled) return; setNodeRef(node); if (asHandle) setActivatorNodeRef(node); }); const composedStyle = React.useMemo<React.CSSProperties>(() => { return { transform: CSS.Translate.toString(transform), transition, ...style, }; }, [transform, transition, style]); const itemContext = React.useMemo<SortableItemContextValue>( () => ({ id, attributes, listeners, setActivatorNodeRef, isDragging, disabled, }), [id, attributes, listeners, setActivatorNodeRef, isDragging, disabled], ); const ItemPrimitive = asChild ? Slot : "div"; return ( <SortableItemContext.Provider value={itemContext}> <ItemPrimitive id={id} data-disabled={disabled} data-dragging={isDragging ? "" : undefined} data-slot="sortable-item" {...itemProps} {...(asHandle && !disabled ? attributes : {})} {...(asHandle && !disabled ? listeners : {})} ref={composedRef} style={composedStyle} className={cn( "focus-visible:outline-hidden focus-visible:ring-1 focus-visible:ring-ring focus-visible:ring-offset-1", { "touch-none select-none": asHandle, "cursor-default": context.flatCursor, "data-dragging:cursor-grabbing": !context.flatCursor, "cursor-grab": !isDragging && asHandle && !context.flatCursor, "opacity-50": isDragging, "pointer-events-none opacity-50": disabled, }, className, )} /> </SortableItemContext.Provider> ); } interface SortableItemHandleProps extends React.ComponentProps<"button"> { asChild?: boolean; } function SortableItemHandle(props: SortableItemHandleProps) { const { asChild, disabled, className, ref, ...itemHandleProps } = props; const context = useSortableContext(ITEM_HANDLE_NAME); const itemContext = useSortableItemContext(ITEM_HANDLE_NAME); const isDisabled = disabled ?? itemContext.disabled; const composedRef = useComposedRefs(ref, (node) => { if (!isDisabled) return; itemContext.setActivatorNodeRef(node); }); const HandlePrimitive = asChild ? Slot : "button"; return ( <HandlePrimitive type="button" aria-controls={itemContext.id} data-disabled={isDisabled} data-dragging={itemContext.isDragging ? "" : undefined} data-slot="sortable-item-handle" {...itemHandleProps} {...(isDisabled ? {} : itemContext.attributes)} {...(isDisabled ? {} : itemContext.listeners)} ref={composedRef} className={cn( "select-none disabled:pointer-events-none disabled:opacity-50", context.flatCursor ? "cursor-default" : "cursor-grab data-dragging:cursor-grabbing", className, )} disabled={isDisabled} /> ); } const SortableOverlayContext = React.createContext(false); const dropAnimation: DropAnimation = { sideEffects: defaultDropAnimationSideEffects({ styles: { active: { opacity: "0.4", }, }, }), }; interface SortableOverlayProps extends Omit<React.ComponentProps<typeof DragOverlay>, "children"> { container?: Element | DocumentFragment | null; children?: | ((params: { value: UniqueIdentifier }) => React.ReactNode) | React.ReactNode; } function SortableOverlay(props: SortableOverlayProps) { const { container: containerProp, children, ...overlayProps } = props; const context = useSortableContext(OVERLAY_NAME); const [mounted, setMounted] = React.useState(false); React.useLayoutEffect(() => setMounted(true), []); const container = containerProp ?? (mounted ? globalThis.document?.body : null); if (!container) return null; return ReactDOM.createPortal( <DragOverlay dropAnimation={dropAnimation} modifiers={context.modifiers} className={cn(!context.flatCursor && "cursor-grabbing")} {...overlayProps} > <SortableOverlayContext.Provider value={true}> {context.activeId ? typeof children === "function" ? children({ value: context.activeId }) : children : null} </SortableOverlayContext.Provider> </DragOverlay>, container, ); } export { Sortable, SortableContent, SortableItem, SortableItemHandle, SortableOverlay, type SortableProps, }; ``` </Step> </Steps> ## Usage [#usage] ### Horizontal [#horizontal] ```tsx export const Horizontal = () => { const [items, setItems] = useState(["1", "2", "3", "4", "5"]); return ( <Sortable value={items} onValueChange={setItems} orientation="horizontal"> <SortableContent className="flex flex-row gap-1"> {items.map((item) => ( <SortableItem key={item} value={item} className="bg-gray-2 border border-gray-6 rounded-md p-1 min-w-12 h-12 flex items-center justify-center text-gray-12" > {item} </SortableItem> ))} </SortableContent> </Sortable> ); }; ``` ### WithHandle [#withhandle] ```tsx export const WithHandle = () => { const [items, setItems] = useState([ "Task 1", "Task 2", "Task 3", "Task 4", ]); return ( <Sortable value={items} onValueChange={setItems}> <SortableContent className="flex flex-col gap-1 w-full max-w-sm"> {items.map((item) => ( <SortableItem key={item} value={item} className="bg-gray-2 border border-gray-6 rounded-md flex items-center gap-1 p-1" > <SortableItemHandle className="cursor-grab active:cursor-grabbing p-0.5 text-gray-11 hover:text-gray-12"> <DragHandleDots2Icon className="icon" /> </SortableItemHandle> <span className="text-gray-12 flex-1">{item}</span> </SortableItem> ))} </SortableContent> </Sortable> ); }; ``` ### WithOverlay [#withoverlay] ```tsx export const WithOverlay = () => { const [items, setItems] = useState([ "Project Alpha", "Project Beta", "Project Gamma", "Project Delta", ]); return ( <Sortable value={items} onValueChange={setItems}> <SortableContent className="flex flex-col gap-1 w-full max-w-sm"> {items.map((item) => ( <SortableItem key={item} value={item} asHandle className="bg-gray-2 border border-gray-6 rounded-md p-1 text-gray-12" > {item} </SortableItem> ))} </SortableContent> <SortableOverlay> {({ value }) => ( <div className="bg-gray-2 border border-gray-7 rounded-md p-1 text-gray-12 shadow-lg"> {items.find((item) => item === value) || value} </div> )} </SortableOverlay> </Sortable> ); }; ``` ### WithHandleAndOverlay [#withhandleandoverlay] ```tsx export const WithHandleAndOverlay = () => { const [items, setItems] = useState([ "Document 1", "Document 2", "Document 3", "Document 4", ]); return ( <Sortable value={items} onValueChange={setItems}> <SortableContent className="flex flex-col gap-1 w-full max-w-sm"> {items.map((item) => ( <SortableItem key={item} value={item} className="bg-gray-2 border border-gray-6 rounded-md flex items-center gap-1 p-1" > <SortableItemHandle className="cursor-grab active:cursor-grabbing p-0.5 text-gray-11 hover:text-gray-12"> <DragHandleDots2Icon className="icon" /> </SortableItemHandle> <span className="text-gray-12 flex-1">{item}</span> </SortableItem> ))} </SortableContent> <SortableOverlay> {({ value }) => ( <div className="bg-gray-2 border border-gray-7 rounded-md flex items-center gap-1 p-1 text-gray-12 shadow-lg"> <div className="p-0.5 text-gray-11"> <DragHandleDots2Icon className="icon" /> </div> <span className="flex-1"> {items.find((item) => item === value) || value} </span> </div> )} </SortableOverlay> </Sortable> ); }; ``` ### DisabledItems [#disableditems] ```tsx export const DisabledItems = () => { const [items, setItems] = useState([ "Active Item 1", "Active Item 2", "Disabled Item", "Active Item 3", ]); return ( <Sortable value={items} onValueChange={setItems}> <SortableContent className="flex flex-col gap-1 w-full max-w-sm"> {items.map((item, index) => ( <SortableItem key={item} value={item} asHandle disabled={index === 2} className="bg-gray-2 border border-gray-6 rounded-md p-1 text-gray-12" > {item} </SortableItem> ))} </SortableContent> </Sortable> ); }; ``` ### WithObjects [#withobjects] ```tsx export const WithObjects = () => { const [items, setItems] = useState([ { id: "1", name: "Apricot", category: "Fruit" }, { id: "2", name: "Carrot", category: "Vegetable" }, { id: "3", name: "Banana", category: "Fruit" }, { id: "4", name: "Broccoli", category: "Vegetable" }, ]); return ( <Sortable value={items} onValueChange={setItems} getItemValue={(item) => item.id} > <SortableContent className="flex flex-col gap-1 w-full max-w-sm"> {items.map((item) => ( <SortableItem key={item.id} value={item.id} asHandle className="bg-gray-2 border border-gray-6 rounded-md p-1" > <div className="flex flex-col gap-0.5"> <span className="text-gray-12 font-medium">{item.name}</span> <span className="text-gray-11 text-sm">{item.category}</span> </div> </SortableItem> ))} </SortableContent> </Sortable> ); }; ``` ### FlatCursor [#flatcursor] ```tsx export const FlatCursor = () => { const [items, setItems] = useState(["Item 1", "Item 2", "Item 3", "Item 4"]); return ( <Sortable value={items} onValueChange={setItems} flatCursor> <SortableContent className="flex flex-col gap-1 w-full max-w-sm"> {items.map((item) => ( <SortableItem key={item} value={item} asHandle className="bg-gray-2 border border-gray-6 rounded-md p-1 text-gray-12" > {item} </SortableItem> ))} </SortableContent> </Sortable> ); }; ``` ### CardList [#cardlist] ```tsx export const CardList = () => { const [items, setItems] = useState([ "Card 1", "Card 2", "Card 3", "Card 4", ]); return ( <Sortable value={items} onValueChange={setItems}> <SortableContent className="flex flex-col gap-1 w-full max-w-sm"> {items.map((item) => ( <SortableItem key={item} value={item} className="bg-gray-2 border border-gray-6 rounded-lg p-1" > <div className="flex items-center gap-1"> <SortableItemHandle className="cursor-grab active:cursor-grabbing p-0.5 text-gray-11 hover:text-gray-12"> <DragHandleDots2Icon className="icon" /> </SortableItemHandle> <div className="flex-1"> <h3 className="text-gray-12 font-medium">{item}</h3> <p className="text-gray-11 text-sm"> Drag to reorder this card </p> </div> </div> </SortableItem> ))} </SortableContent> <SortableOverlay> {({ value }) => ( <div className="bg-gray-2 border border-gray-7 rounded-lg p-2 shadow-lg"> <div className="flex items-center gap-1"> <div className="p-0.5 text-gray-11"> <DragHandleDots2Icon className="icon" /> </div> <div className="flex-1"> <h3 className="text-gray-12 font-medium"> {items.find((item) => item === value) || value} </h3> <p className="text-gray-11 text-sm">Dragging...</p> </div> </div> </div> )} </SortableOverlay> </Sortable> ); }; ``` ### NumberedList [#numberedlist] ```tsx export const NumberedList = () => { const [items, setItems] = useState([ "First item", "Second item", "Third item", "Fourth item", ]); return ( <Sortable value={items} onValueChange={setItems}> <SortableContent className="flex flex-col gap-1 w-full max-w-sm"> {items.map((item, index) => ( <SortableItem key={item} value={item} className="bg-gray-2 border border-gray-6 rounded-md flex items-center gap-1 p-1" > <div className="flex items-center justify-center w-6 h-6 rounded-sm bg-gray-4 text-gray-12 text-sm font-medium"> {index + 1} </div> <span className="text-gray-12 flex-1">{item}</span> <SortableItemHandle className="cursor-grab active:cursor-grabbing p-0.5 text-gray-11 hover:text-gray-12"> <DragHandleDots2Icon className="icon" /> </SortableItemHandle> </SortableItem> ))} </SortableContent> </Sortable> ); }; ``` ### MixedOrientation [#mixedorientation] ```tsx export const MixedOrientation = () => { const [items, setItems] = useState(["1", "2", "3", "4", "5", "6"]); return ( <Sortable value={items} onValueChange={setItems} orientation="mixed"> <SortableContent className="grid grid-cols-3 gap-1 w-full max-w-sm"> {items.map((item) => ( <SortableItem key={item} value={item} asHandle className="bg-gray-2 border border-gray-6 rounded-md p-1 aspect-square flex items-center justify-center text-gray-12" > {item} </SortableItem> ))} </SortableContent> </Sortable> ); }; ``` ### WithOnMove [#withonmove] ```tsx export const WithOnMove = () => { const [items, setItems] = useState(["A", "B", "C", "D"]); const [lastMove, setLastMove] = useState<string>(""); return ( <div className="flex flex-col gap-2 w-full max-w-sm"> <Sortable value={items} onValueChange={setItems} onMove={(event) => { setLastMove( `Moved from position ${event.activeIndex + 1} to ${event.overIndex + 1}`, ); }} > <SortableContent className="flex flex-col gap-1"> {items.map((item) => ( <SortableItem key={item} value={item} asHandle className="bg-gray-2 border border-gray-6 rounded-md p-1 text-gray-12" > {item} </SortableItem> ))} </SortableContent> </Sortable> {lastMove && ( <p className="text-gray-11 text-sm">Last move: {lastMove}</p> )} </div> ); }; ``` # Speed Dial (/docs/components/speed-dial) ## Preview [#preview] <ComponentPreview name="speed-dial-demo" description="A floating button that opens a stack of actions. Same parts as the floating action menu."> ```tsx import { ImageIcon, Link2Icon } from "@radix-ui/react-icons"; import { SpeedDial, SpeedDialItem, SpeedDialList, SpeedDialTrigger, } from "@/components/ui/SpeedDial"; export function SpeedDialDemo() { return ( <SpeedDial defaultOpen> <div className="relative h-24 w-full rounded-sm border border-gray-6 bg-gray-2"> <SpeedDialList position="absolute"> <SpeedDialItem label="Image"> <ImageIcon className="icon" /> </SpeedDialItem> <SpeedDialItem label="Link"> <Link2Icon className="icon" /> </SpeedDialItem> </SpeedDialList> <SpeedDialTrigger position="absolute" /> </div> </SpeedDial> ); } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/speed-dial ``` ### Manual [#manual] <Steps> <Step> Copy and paste the SpeedDial component into your `components/ui/SpeedDial.tsx` file. ```tsx "use client"; export { SpeedDial, SpeedDialItem, SpeedDialList, SpeedDialTrigger, } from "@/components/ui/FabMenu"; ``` </Step> </Steps> # Spinner (/docs/components/spinner) ## Preview [#preview] <ComponentPreview name="spinner-demo" description="A status spinner reused by Button and FormSubmit."> ```tsx import { Spinner } from "@/components/ui/Spinner"; export function SpinnerDemo() { return <Spinner label="Loading" />; } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/spinner ``` ### Manual [#manual] <Steps> <Step> Install the following dependencies: ```bash pnpm install @radix-ui/react-icons ``` </Step> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the Spinner component into your `components/ui/Spinner.tsx` file. ```tsx "use client"; /** * @description A status spinner. Buttons reuse it while a submit is in flight. / import as React from "react"; import { SymbolIcon } from "@radix-ui/react-icons"; import { cn } from "@/utils/class-names"; function Spinner({ className, label, ...props }: React.ComponentProps<"span"> & { label?: string; }) { return ( <span data-slot="spinner" role={label ? "status" : undefined} className={cn("inline-flex", className)} {...props} > <SymbolIcon className="icon animate-spin motion-reduce:animate-none" aria-hidden /> {label ? <span className="sr-only">{label}</span> : null} </span> ); } export { Spinner }; ``` </Step> </Steps> # Split Button (/docs/components/split-button) ## Preview [#preview] <ComponentPreview name="split-button-demo" description="A main action paired with a menu of related actions."> ```tsx import { Pencil2Icon, TrashIcon } from "@radix-ui/react-icons"; import { SplitButton, SplitButtonAction, SplitButtonMenu } from "@/components/ui/SplitButton"; import { DropdownMenuItem } from "@/components/ui/DropdownMenu"; export function SplitButtonDemo() { return ( <SplitButton> <SplitButtonAction>Save</SplitButtonAction> <SplitButtonMenu> <DropdownMenuItem> <Pencil2Icon className="icon" /> Save as draft </DropdownMenuItem> <DropdownMenuItem> <TrashIcon className="icon" /> Discard </DropdownMenuItem> </SplitButtonMenu> </SplitButton> ); } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/split-button ``` ### Manual [#manual] <Steps> <Step> Install the following dependencies: ```bash pnpm install @radix-ui/react-icons ``` </Step> <Step> Copy and paste the button component into your `components/ui/Button.tsx` file. ```tsx /** * @description Displays a button or a component that looks like a button. / import as React from "react"; import { Slot } from "@radix-ui/react-slot"; import { cva, type VariantProps } from "class-variance-authority"; import { cn } from "@/utils/class-names"; import { Spinner } from "@/components/ui/Spinner"; const buttonVariants = cva("button", { variants: { variant: { default: "button-fill", fill: "button-fill", pill: "button-pill border border-gray-6 text-gray-11 bg-gray-2 hover:bg-gray-3", link: "button-link", menu: "button-menu", }, size: { default: "h-4", xs: "h-2.5", sm: "h-3", md: "h-4", lg: "h-5", xl: "h-6", icon: "w-3 h-3 p-0", "icon-md": "w-4 h-4 p-0", }, }, defaultVariants: { variant: "default", size: "default", }, }); interface ButtonProps extends React.ComponentProps<"button">, VariantProps<typeof buttonVariants> { asChild?: boolean; isDisabled?: boolean; isLoading?: boolean; isLoadingText?: string | React.ReactNode; mode?: VariantProps<typeof buttonVariants>["variant"]; label?: string | React.ReactNode; } const Button = React.forwardRef<HTMLButtonElement, ButtonProps>( (props: ButtonProps, ref) => { const { className, variant, mode, size, asChild = false, isDisabled, isLoading, isLoadingText, children, label, ...rest } = props; const Comp = asChild ? Slot : "button"; const disabled = isDisabled || isLoading || props.disabled; const effectiveVariant = variant ?? mode; return ( <Comp data-slot="button" className={cn( buttonVariants({ variant: effectiveVariant, size, className }), disabled && "opacity-50 cursor-not-allowed" )} ref={ref} disabled={disabled} {...rest} > {asChild ? ( children ) : ( <> {isLoading && isLoadingText ? ( isLoadingText ) : ( <> {isLoading ? <Spinner /> : null} {label} {children} </> )} </> )} </Comp> ); } ); Button.displayName = "Button"; export { Button, buttonVariants }; export type { ButtonProps }; export default Button; ``` </Step> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the dropdown menu component into your `components/ui/DropdownMenu.tsx` file. ```tsx "use client"; /** * @description Displays a menu of actions or options triggered by a button. / import as React from "react"; import { DropdownMenu as DropdownMenuRadix } from "radix-ui"; import { CheckIcon, ChevronRightIcon, CircleIcon, DotFilledIcon, } from "@radix-ui/react-icons"; import { cn } from "@/utils/class-names"; function DropdownMenu({ ...props }: React.ComponentProps<typeof DropdownMenuRadix.Root>) { return <DropdownMenuRadix.Root data-slot="dropdown-menu" {...props} />; } function DropdownMenuPortal({ ...props }: React.ComponentProps<typeof DropdownMenuRadix.Portal>) { return ( <DropdownMenuRadix.Portal data-slot="dropdown-menu-portal" {...props} /> ); } function DropdownMenuTrigger({ className, ...props }: React.ComponentProps<typeof DropdownMenuRadix.Trigger>) { return ( <DropdownMenuRadix.Trigger data-slot="dropdown-menu-trigger" className={cn(className)} {...props} /> ); } function DropdownMenuContent({ className, ...props }: React.ComponentProps<typeof DropdownMenuRadix.Content>) { return ( <DropdownMenuRadix.Portal> <DropdownMenuRadix.Content data-slot="dropdown-menu-content" collisionPadding={8} className={cn( className, "z-50 origin-(--radix-dropdown-menu-content-transform-origin) bg-gray-1 border border-gray-a6 rounded-sm relative shadow-md data-[state=open]:animate-popover-show data-[state=closed]:animate-popover-hide" )} {...props} /> </DropdownMenuRadix.Portal> ); } function DropdownMenuGroup({ ...props }: React.ComponentProps<typeof DropdownMenuRadix.Group>) { return <DropdownMenuRadix.Group data-slot="dropdown-menu-group" {...props} />; } function DropdownMenuItem({ className, ...props }: React.ComponentProps<typeof DropdownMenuRadix.Item>) { return ( <DropdownMenuRadix.Item data-slot="dropdown-menu-item" className={cn( className, "p-0.5 px-2 hover:bg-accent-3 flex relative cursor-pointer" )} {...props} /> ); } function DropdownMenuCheckboxItem({ children, className, ...props }: React.ComponentProps<typeof DropdownMenuRadix.CheckboxItem>) { return ( <DropdownMenuRadix.CheckboxItem data-slot="dropdown-menu-checkbox-item" className={cn( className, "p-0.5 px-2 hover:bg-accent-3 flex relative cursor-pointer" )} {...props} > <span className="absolute left-0.5 top-0 bottom-0 items-center flex justify-center"> <DropdownMenuRadix.ItemIndicator> <CheckIcon className="text-accent-9" /> </DropdownMenuRadix.ItemIndicator> </span> {children} </DropdownMenuRadix.CheckboxItem> ); } function DropdownMenuRadioGroup({ className, ...props }: React.ComponentProps<typeof DropdownMenuRadix.RadioGroup>) { return ( <DropdownMenuRadix.RadioGroup data-slot="dropdown-menu-radio-group" className={cn(className)} {...props} /> ); } function DropdownMenuRadioItem({ children, className, ...props }: React.ComponentProps<typeof DropdownMenuRadix.RadioItem>) { return ( <DropdownMenuRadix.RadioItem data-slot="dropdown-menu-radio-item" className={cn( className, "p-0.5 px-2 hover:bg-accent-3 flex relative cursor-pointer" )} {...props} > <span className="absolute left-0.5 top-0 bottom-0 items-center flex justify-center"> <DropdownMenuRadix.ItemIndicator> <DotFilledIcon className="fill-current text-accent-9" /> </DropdownMenuRadix.ItemIndicator> </span> {children} </DropdownMenuRadix.RadioItem> ); } function DropdownMenuLabel({ className, ...props }: React.ComponentProps<typeof DropdownMenuRadix.Label>) { return ( <DropdownMenuRadix.Label data-slot="dropdown-menu-label" className={cn(className, "p-0.5 px-2 text-gray-12")} {...props} /> ); } function DropdownMenuSeparator({ className, ...props }: React.ComponentProps<typeof DropdownMenuRadix.Separator>) { return ( <DropdownMenuRadix.Separator data-slot="dropdown-menu-separator" className={cn(className, "m-0.6 h-px bg-gray-a6")} {...props} /> ); } function DropdownMenuShortcut({ ...props }: React.ComponentProps<"span">) { return <span data-slot="dropdown-menu-shortcut" {...props} />; } function DropdownMenuSub({ ...props }: React.ComponentProps<typeof DropdownMenuRadix.Sub>) { return <DropdownMenuRadix.Sub data-slot="dropdown-menu-sub" {...props} />; } function DropdownMenuSubTrigger({ children, className, ...props }: React.ComponentProps<typeof DropdownMenuRadix.SubTrigger>) { return ( <DropdownMenuRadix.SubTrigger data-slot="dropdown-menu-sub-trigger" className={cn( className, "p-0.5 px-2 hover:bg-accent-3 flex relative cursor-pointer" )} {...props} > {children} <div className="absolute right-0.5 top-0 bottom-0 items-center flex justify-center"> <ChevronRightIcon /> </div> </DropdownMenuRadix.SubTrigger> ); } function DropdownMenuSubContent({ className, ...props }: React.ComponentProps<typeof DropdownMenuRadix.SubContent>) { return ( <DropdownMenuRadix.SubContent data-slot="dropdown-menu-sub-content" className={cn( className, "z-50 origin-(--radix-dropdown-menu-content-transform-origin) bg-gray-1 border border-gray-a6 rounded-sm relative shadow-md data-[state=open]:animate-popover-show data-[state=closed]:animate-popover-hide" )} {...props} /> ); } export { DropdownMenu, DropdownMenuPortal, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuGroup, DropdownMenuLabel, DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubTrigger, DropdownMenuSubContent, }; ``` </Step> <Step> Copy and paste the SplitButton component into your `components/ui/SplitButton.tsx` file. ```tsx "use client"; import * as React from "react"; import { ChevronDownIcon } from "@radix-ui/react-icons"; import { cn } from "@/utils/class-names"; import { Button, type ButtonProps } from "@/components/ui/Button"; import { DropdownMenu, DropdownMenuContent, DropdownMenuTrigger, } from "@/components/ui/DropdownMenu"; function SplitButton({ className, ...props }: React.ComponentProps<"div">) { return ( <div role="group" data-slot="split-button" className={cn( "inline-flex items-stretch overflow-hidden rounded-sm", className, )} {...props} /> ); } function SplitButtonAction({ className, ...props }: ButtonProps) { return ( <Button data-slot="split-button-action" className={cn("rounded-r-none", className)} {...props} /> ); } function SplitButtonMenu({ className, label = "More actions", children, ...props }: React.ComponentProps<typeof DropdownMenuContent> & { label?: string }) { return ( <DropdownMenu> <DropdownMenuTrigger asChild> <Button data-slot="split-button-menu" aria-label={label} className="w-4 rounded-none border-l border-accent-a7 px-0" > <ChevronDownIcon className="icon" /> </Button> </DropdownMenuTrigger> <DropdownMenuContent align="end" className={className} {...props}> {children} </DropdownMenuContent> </DropdownMenu> ); } export { SplitButton, SplitButtonAction, SplitButtonMenu }; ``` </Step> </Steps> # Stack (/docs/components/stack) ## Preview [#preview] <ComponentPreview name="stack-demo" description="Overlapping panels offset from one another."> ```tsx import { Stack } from "@/components/ui/Stack"; export function StackDemo() { return ( <Stack> <span>One</span> <span>Two</span> <span>Three</span> </Stack> ) } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/stack ``` ### Manual [#manual] <Steps> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the Stack component into your `components/ui/Stack.tsx` file. ```tsx "use client"; import * as React from "react"; import { cn } from "@/utils/class-names"; function Stack({ className, children, ...props }: React.ComponentProps<"div">) { const items = React.Children.toArray(children); return ( <div data-slot="stack" className={cn("relative h-16 w-16", className)} {...props}> {items.map((child, index) => ( <div key={index} className="absolute inset-0 rounded-sm border border-gray-6 bg-gray-1 p-1 shadow-sm" style={{ transform: `translate(${index * 8}px, ${index * 8}px)` }} > {child} </div> ))} </div> ); } export { Stack }; ``` </Step> </Steps> # Stat (/docs/components/stat) ## Preview [#preview] <ComponentPreview name="stat-demo" description="Displays a statistic with label, value, optional indicator, trend, and description."> ```tsx import { ArrowDownIcon, ArrowUpIcon, Cross2Icon, DotsHorizontalIcon, EnvelopeClosedIcon, PersonIcon, ReaderIcon, } from "@radix-ui/react-icons"; import { Stat, StatDescription, StatIndicator, StatLabel, StatSeparator, StatTrend, StatValue, } from "@/components/ui/Stat"; export function StatDemo() { return ( <Stat className="max-w-xs"> <StatLabel>Total Revenue</StatLabel> <StatIndicator variant="icon" color="success"> <ReaderIcon className="icon" aria-hidden /> </StatIndicator> <StatValue>$45,231</StatValue> <StatTrend trend="up"> <ArrowUpIcon className="icon" aria-hidden /> +20.1% from last month </StatTrend> <StatSeparator /> <StatDescription> Total revenue generated in the current billing period </StatDescription> </Stat> ) } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/stat ``` ### Manual [#manual] <Steps> <Step> Install the following dependencies: ```bash pnpm install class-variance-authority ``` </Step> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the separator component into your `components/ui/Separator.tsx` file. ```tsx "use client" import * as React from "react" import {Separator as SeparatorPrimitive} from "radix-ui" import { cn } from "@/utils/class-names" function Separator({ className, orientation = "horizontal", decorative = true, ...props }: React.ComponentProps<typeof SeparatorPrimitive.Root>) { return ( <SeparatorPrimitive.Root data-slot="separator" decorative={decorative} orientation={orientation} className={cn( "bg-gray-a6 shrink-0 data-[orientation=horizontal]:h-px data-[orientation=horizontal]:w-full data-[orientation=vertical]:h-full data-[orientation=vertical]:w-px", className )} {...props} /> ) } export { Separator } ``` </Step> <Step> Copy and paste the Stat component into your `components/ui/Stat.tsx` file. ```tsx /** * @description Displays a statistic with label, value, optional indicator, trend, and description. / import as React from "react"; import { cva, type VariantProps } from "class-variance-authority"; import { cn } from "@/utils/class-names"; import { Separator } from "@/components/ui/Separator"; function Stat({ className, ...props }: React.ComponentProps<"div">) { return ( <div data-slot="stat" className={cn( "grid grid-cols-[1fr_auto] gap-x-1.5 gap-y-0.5 rounded-md border border-gray-6 bg-gray-2 p-1.5 text-gray-12", ":data-[slot=stat-label]:col-span-1 :data-[slot=stat-value]:col-span-1", ":data-[slot=stat-indicator]:col-start-2 :data-[slot=stat-indicator]:row-span-2 :data-[slot=stat-indicator]:row-start-1 :data-[slot=stat-indicator]:self-start", ":data-[slot=stat-description]:col-span-2 :data-[slot=stat-separator]:col-span-2 :data-[slot=stat-trend]:col-span-2", className )} {...props} /> ); } function StatLabel({ className, ...props }: React.ComponentProps<"div">) { return ( <div data-slot="stat-label" className={cn("text-sm font-medium text-gray-11", className)} {...props} /> ); } const statIndicatorVariants = cva( "flex shrink-0 items-center justify-center [&_svg]:pointer-events-none", { variants: { variant: { default: "text-gray-11", icon: "size-2.5 rounded-md border", badge: "h-2 min-w-2 rounded-sm border px-0.5 text-xs font-medium", action: "size-2.5 cursor-pointer rounded-md transition-colors hover:bg-gray-3", }, color: { default: "bg-gray-3 text-gray-11 border-gray-6", success: "border-success/20 bg-success/10 text-success-contrast", info: "border-info/20 bg-info/10 text-info-contrast", warning: "border-warning/20 bg-warning/10 text-warning-contrast", error: "border-danger/20 bg-danger/10 text-danger-contrast", }, }, compoundVariants: [ { variant: "default", color: "default", class: "bg-transparent border-transparent", }, ], defaultVariants: { variant: "default", color: "default", }, } ); interface StatIndicatorProps extends Omit<React.ComponentProps<"div">, "color">, VariantProps<typeof statIndicatorVariants> {} function StatIndicator({ className, variant = "default", color = "default", ...props }: StatIndicatorProps) { return ( <div data-slot="stat-indicator" data-variant={variant} data-color={color} className={cn(statIndicatorVariants({ variant, color }), className)} {...props} /> ); } function StatValue({ className, ...props }: React.ComponentProps<"div">) { return ( <div data-slot="stat-value" className={cn("h4 font-semibold tracking-tight text-gray-12", className)} {...props} /> ); } function StatTrend({ className, trend, ...props }: React.ComponentProps<"div"> & { trend?: "up" | "down" | "neutral" }) { return ( <div data-slot="stat-trend" data-trend={trend} className={cn( "inline-flex items-center gap-0.5 text-xs font-medium [&_svg]:pointer-events-none [&_svg]:shrink-0", { "text-success-contrast": trend === "up", "text-danger-contrast": trend === "down", "text-gray-11": trend === "neutral" || !trend, }, className )} {...props} /> ); } function StatSeparator({ className, ...props }: React.ComponentProps<typeof Separator>) { return ( <Separator data-slot="stat-separator" className={cn("my-0.5", className)} {...props} /> ); } function StatDescription({ className, ...props }: React.ComponentProps<"div">) { return ( <div data-slot="stat-description" className={cn("text-xs text-gray-11", className)} {...props} /> ); } export { Stat, StatDescription, StatIndicator, StatLabel, StatSeparator, StatTrend, StatValue, statIndicatorVariants, }; ``` </Step> </Steps> ## Usage [#usage] ### IndicatorVariants [#indicatorvariants] ```tsx export const IndicatorVariants = () => ( <div className="flex flex-wrap gap-1"> <Stat className="max-w-xs"> <StatLabel>Default</StatLabel> <StatIndicator> <PersonIcon className="icon" aria-hidden /> </StatIndicator> <StatValue>1,204</StatValue> </Stat> <Stat className="max-w-xs"> <StatLabel>Icon</StatLabel> <StatIndicator variant="icon" color="info"> <EnvelopeClosedIcon className="icon" aria-hidden /> </StatIndicator> <StatValue>892</StatValue> </Stat> <Stat className="max-w-xs"> <StatLabel>Badge</StatLabel> <StatIndicator variant="badge" color="warning"> New </StatIndicator> <StatValue>64</StatValue> </Stat> <Stat className="max-w-xs"> <StatLabel>Action</StatLabel> <StatIndicator variant="action" color="default" role="button" tabIndex={0}> <DotsHorizontalIcon className="icon" aria-hidden /> </StatIndicator> <StatValue>318</StatValue> </Stat> </div> ) ``` ### Trends [#trends] ```tsx export const Trends = () => ( <div className="flex flex-wrap gap-1"> <Stat className="max-w-xs"> <StatLabel>Active users</StatLabel> <StatValue>12,480</StatValue> <StatTrend trend="up"> <ArrowUpIcon className="icon" aria-hidden /> +4.2% </StatTrend> </Stat> <Stat className="max-w-xs"> <StatLabel>Churn</StatLabel> <StatValue>2.1%</StatValue> <StatTrend trend="down"> <ArrowDownIcon className="icon" aria-hidden /> -0.4% </StatTrend> </Stat> <Stat className="max-w-xs"> <StatLabel>Open tickets</StatLabel> <StatIndicator variant="icon" color="error"> <Cross2Icon className="icon" aria-hidden /> </StatIndicator> <StatValue>37</StatValue> <StatTrend trend="neutral">No change</StatTrend> </Stat> </div> ) ``` ### WithDescription [#withdescription] ```tsx export const WithDescription = () => ( <Stat className="max-w-sm"> <StatLabel>Conversion rate</StatLabel> <StatIndicator variant="badge" color="success"> Live </StatIndicator> <StatValue>3.24%</StatValue> <StatTrend trend="up"> <ArrowUpIcon className="icon" aria-hidden /> +0.3% vs prior week </StatTrend> <StatSeparator /> <StatDescription> Share of sessions that completed checkout in the last 7 days. </StatDescription> </Stat> ) ``` # Status Dot (/docs/components/status-dot) ## Preview [#preview] <ComponentPreview name="status-dot-demo" description="A 10px status dot for queued, building, error, ready, and canceled."> ```tsx import { StatusDot } from "@/components/ui/StatusDot"; export function StatusDotDemo() { return ( <div className="flex flex-col gap-2"> <div className="flex items-center gap-2"> <StatusDot state="queued" /> <StatusDot state="building" /> <StatusDot state="error" /> <StatusDot state="ready" /> <StatusDot state="canceled" /> </div> <div className="flex flex-wrap items-center gap-2"> <StatusDot state="queued" label /> <StatusDot state="building" label /> <StatusDot state="error" label /> <StatusDot state="ready" label /> <StatusDot state="canceled" label /> </div> </div> ) } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/status-dot ``` ### Manual [#manual] <Steps> <Step> Install the following dependencies: ```bash pnpm install class-variance-authority ``` </Step> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the StatusDot component into your `components/ui/StatusDot.tsx` file. ```tsx / * @description A 10px status dot for queued, building, error, ready, and canceled. / import as React from "react"; import { cva } from "class-variance-authority"; import { cn } from "@/utils/class-names"; const STATES = { queued: { label: "Queued", message: "Queued." }, building: { label: "Building", message: "In progress." }, error: { label: "Error", message: "Failed." }, ready: { label: "Ready", message: "Ready." }, canceled: { label: "Canceled", message: "Canceled." }, } as const; type StatusDotState = keyof typeof STATES; const dot = cva("inline-block size-[10px] shrink-0 rounded-full", { variants: { state: { queued: "bg-status-dot-queued", building: "bg-status-dot-building", error: "bg-status-dot-error", ready: "bg-status-dot-ready", canceled: "bg-status-dot-canceled", }, ring: { true: "ring-2 ring-status-dot-ring", false: "" }, }, defaultVariants: { state: "queued", ring: false }, }); interface StatusDotProps extends React.ComponentProps<"span"> { state?: StatusDotState; /** `true` uses the state name. A string replaces it. */ label?: boolean | string; /** Light ring for overlaying the dot on an avatar. / ring?: boolean; } function StatusDot({ state = "queued", label, ring, className, ...props }: StatusDotProps) { const s = STATES[state]; return ( <span data-slot="status-dot" data-state={state} role="status" aria-label={s.label} title={s.message} className={cn("inline-flex items-center gap-[8px]", className)} {...props} > <span data-slot="status-dot-indicator" aria-hidden className={dot({ state, ring })} /> {label ? ( <span className="text-sm font-medium text-gray-12"> {label === true ? s.label : label} </span> ) : null} </span> ); } export { StatusDot, type StatusDotState }; ``` </Step> </Steps> ## Usage [#usage] ### WithRing [#withring] ```tsx export const WithRing = () => ( <div className="flex items-center gap-2 rounded-md bg-gray-12 p-2"> <StatusDot state="ready" ring /> <StatusDot state="building" ring /> <StatusDot state="error" ring /> <StatusDot state="queued" ring /> <StatusDot state="canceled" ring /> </div> ) ``` ### CustomLabel [#customlabel] ```tsx export const CustomLabel = () => ( <StatusDot state="building" label="Deploying" /> ) ``` # Status (/docs/components/status) ## Preview [#preview] <ComponentPreview name="status-demo" description="A short status label with a tone dot."> ```tsx import { Status } from "@/components/ui/Status"; export function StatusDemo() { return ( <div className="flex flex-col gap-0.5"> <Status tone="online">Online</Status> <Status tone="away">Away</Status> <Status tone="busy">Busy</Status> <Status tone="offline">Offline</Status> </div> ) } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/status ``` ### Manual [#manual] <Steps> <Step> Install the following dependencies: ```bash pnpm install class-variance-authority ``` </Step> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the Status component into your `components/ui/Status.tsx` file. ```tsx "use client"; import as React from "react"; import { cva, type VariantProps } from "class-variance-authority"; import { cn } from "@/utils/class-names"; const statusVariants = cva("inline-flex items-center gap-0.5", { variants: { tone: { online: "text-gray-12", away: "text-gray-12", busy: "text-gray-12", offline: "text-gray-11", }, }, defaultVariants: { tone: "online" }, }); const dot = { online: "bg-accent-9", away: "bg-gray-9", busy: "bg-gray-12", offline: "bg-gray-7", } as const; function Status({ className, tone = "online", children, ...props }: React.ComponentProps<"span"> & VariantProps<typeof statusVariants>) { const current = tone ?? "online"; return ( <span data-slot="status" data-tone={current} className={cn(statusVariants({ tone: current }), className)} {...props} > <span aria-hidden className={cn("size-1 rounded-full", dot[current])} /> {children} </span> ); } export { Status }; ``` </Step> </Steps> # Stepper (/docs/components/stepper) ## Preview [#preview] <ComponentPreview name="stepper-demo" description="A sequential progress indicator with navigation controls."> ```tsx import { Stepper, StepperList, StepperItem, StepperTrigger, StepperIndicator, StepperSeparator, StepperTitle, StepperDescription, StepperContent, StepperPrev, StepperNext, } from "@/components/ui/Stepper"; export function StepperDemo() { return ( <Stepper defaultValue="step-1" className="w-full"> <StepperList> <StepperItem value="step-1"> <StepperTrigger> <StepperIndicator /> <div className="flex flex-col"> <StepperTitle>Step 1</StepperTitle> <StepperDescription>Complete your profile</StepperDescription> </div> </StepperTrigger> <StepperSeparator /> </StepperItem> <StepperItem value="step-2"> <StepperTrigger> <StepperIndicator /> <div className="flex flex-col"> <StepperTitle>Step 2</StepperTitle> <StepperDescription>Verify your email</StepperDescription> </div> </StepperTrigger> <StepperSeparator /> </StepperItem> <StepperItem value="step-3"> <StepperTrigger> <StepperIndicator /> <div className="flex flex-col"> <StepperTitle>Step 3</StepperTitle> <StepperDescription>Set up your preferences</StepperDescription> </div> </StepperTrigger> <StepperSeparator /> </StepperItem> </StepperList> <StepperContent value="step-1"> <div className="p-4">Content for step 1</div> </StepperContent> <StepperContent value="step-2"> <div className="p-4">Content for step 2</div> </StepperContent> <StepperContent value="step-3"> <div className="p-4">Content for step 3</div> </StepperContent> </Stepper> ); } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/stepper ``` ### Manual [#manual] <Steps> <Step> Install the following dependencies: ```bash pnpm install @radix-ui/react-direction @radix-ui/react-icons @radix-ui/react-slot ``` </Step> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the compose refs utility into your `utils/compose-refs.tsx` file. ```tsx /** * @see https://github.com/radix-ui/primitives/blob/main/packages/react/compose-refs/src/compose-refs.tsx / import as React from "react"; type PossibleRef<T> = React.Ref<T> | undefined; /** * Set a given ref to a given value * This utility takes care of different types of refs: callback refs and RefObject(s) */ function setRef<T>(ref: PossibleRef<T>, value: T) { if (typeof ref === "function") { return ref(value); } if (ref !== null && ref !== undefined) { ref.current = value; } } /** * A utility to compose multiple refs together * Accepts callback refs and RefObject(s) */ function composeRefs<T>(...refs: PossibleRef<T>[]): React.RefCallback<T> { return (node) => { let hasCleanup = false; const cleanups = refs.map((ref) => { const cleanup = setRef(ref, node); if (!hasCleanup && typeof cleanup === "function") { hasCleanup = true; } return cleanup; }); // React <19 will log an error to the console if a callback ref returns a // value. We don't use ref cleanups internally so this will only happen if a // user's ref callback returns a value, which we only expect if they are // using the cleanup functionality added in React 19. if (hasCleanup) { return () => { for (let i = 0; i < cleanups.length; i++) { const cleanup = cleanups[i]; if (typeof cleanup === "function") { cleanup(); } else { setRef(refs[i], null); } } }; } }; } /** * A custom hook that composes multiple refs * Accepts callback refs and RefObject(s) / function useComposedRefs<T>(...refs: PossibleRef<T>[]): React.RefCallback<T> { // biome-ignore lint/correctness/useExhaustiveDependencies: we want to memoize by all values return React.useCallback(composeRefs(...refs), refs); } export { composeRefs, useComposedRefs }; ``` </Step> <Step> Copy and paste the use as ref hook into your `hooks/use-as-ref.ts` file. ```ts import as React from "react"; import { useIsomorphicLayoutEffect } from "@/hooks/use-isomorphic-layout-effect"; function useAsRef<T>(props: T) { const ref = React.useRef<T>(props); useIsomorphicLayoutEffect(() => { ref.current = props; }); return ref; } export { useAsRef }; ``` </Step> <Step> Copy and paste the use isomorphic layout effect hook into your `hooks/use-isomorphic-layout-effect.ts` file. ```ts import * as React from "react"; const useIsomorphicLayoutEffect = typeof window !== "undefined" ? React.useLayoutEffect : React.useEffect; export { useIsomorphicLayoutEffect }; ``` </Step> <Step> Copy and paste the use lazy ref hook into your `hooks/use-lazy-ref.ts` file. ```ts import * as React from "react"; function useLazyRef<T>(fn: () => T) { const ref = React.useRef<T | null>(null); if (ref.current === null) { ref.current = fn(); } return ref as React.RefObject<T>; } export { useLazyRef }; ``` </Step> <Step> Copy and paste the Stepper component into your `components/ui/Stepper.tsx` file. ```tsx "use client"; import { useDirection } from "@radix-ui/react-direction"; import { Slot } from "@radix-ui/react-slot"; import { CheckIcon } from "@radix-ui/react-icons"; import * as React from "react"; import { useComposedRefs } from "@/utils/compose-refs"; import { cn } from "@/utils/class-names"; import { useAsRef } from "@/hooks/use-as-ref"; import { useIsomorphicLayoutEffect } from "@/hooks/use-isomorphic-layout-effect"; import { useLazyRef } from "@/hooks/use-lazy-ref"; const ROOT_NAME = "Stepper"; const LIST_NAME = "StepperList"; const ITEM_NAME = "StepperItem"; const TRIGGER_NAME = "StepperTrigger"; const INDICATOR_NAME = "StepperIndicator"; const SEPARATOR_NAME = "StepperSeparator"; const TITLE_NAME = "StepperTitle"; const DESCRIPTION_NAME = "StepperDescription"; const CONTENT_NAME = "StepperContent"; const PREV_NAME = "StepperPrev"; const NEXT_NAME = "StepperNext"; const ENTRY_FOCUS = "stepperFocusGroup.onEntryFocus"; const EVENT_OPTIONS = { bubbles: false, cancelable: true }; const ARROW_KEYS = ["ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight"]; type Direction = "ltr" | "rtl"; type Orientation = "horizontal" | "vertical"; type NavigationDirection = "next" | "prev"; type ActivationMode = "automatic" | "manual"; type DataState = "inactive" | "active" | "completed"; interface DivProps extends React.ComponentProps<"div"> { asChild?: boolean; } interface ButtonProps extends React.ComponentProps<"button"> { asChild?: boolean; } type ListElement = React.ComponentRef<typeof StepperList>; type TriggerElement = React.ComponentRef<typeof StepperTrigger>; function getId( id: string, variant: "trigger" | "content" | "title" | "description", value: string, ) { return `${id}-${variant}-${value}`; } type FocusIntent = "first" | "last" | "prev" | "next"; const MAP_KEY_TO_FOCUS_INTENT: Record<string, FocusIntent> = { ArrowLeft: "prev", ArrowUp: "prev", ArrowRight: "next", ArrowDown: "next", PageUp: "first", Home: "first", PageDown: "last", End: "last", }; function getDirectionAwareKey(key: string, dir?: Direction) { if (dir !== "rtl") return key; return key === "ArrowLeft" ? "ArrowRight" : key === "ArrowRight" ? "ArrowLeft" : key; } function getFocusIntent( event: React.KeyboardEvent<TriggerElement>, dir?: Direction, orientation?: Orientation, ) { const key = getDirectionAwareKey(event.key, dir); if (orientation === "horizontal" && ["ArrowUp", "ArrowDown"].includes(key)) return undefined; if (orientation === "vertical" && ["ArrowLeft", "ArrowRight"].includes(key)) return undefined; return MAP_KEY_TO_FOCUS_INTENT[key]; } function focusFirst( candidates: React.RefObject<TriggerElement | null>[], preventScroll = false, ) { const PREVIOUSLY_FOCUSED_ELEMENT = document.activeElement; for (const candidateRef of candidates) { const candidate = candidateRef.current; if (!candidate) continue; if (candidate === PREVIOUSLY_FOCUSED_ELEMENT) return; candidate.focus({ preventScroll }); if (document.activeElement !== PREVIOUSLY_FOCUSED_ELEMENT) return; } } function wrapArray<T>(array: T[], startIndex: number) { return array.map<T>( (_, index) => array[(startIndex + index) % array.length] as T, ); } function getDataState( value: string | undefined, itemValue: string, stepState: StepState | undefined, steps: Map<string, StepState>, variant: "item" | "separator" = "item", ): DataState { const stepKeys = Array.from(steps.keys()); const currentIndex = stepKeys.indexOf(itemValue); if (stepState?.completed) return "completed"; if (value === itemValue) { return variant === "separator" ? "inactive" : "active"; } if (value) { const activeIndex = stepKeys.indexOf(value); if (activeIndex > currentIndex) return "completed"; } return "inactive"; } interface StepState { value: string; completed: boolean; disabled: boolean; } interface StoreState { steps: Map<string, StepState>; value: string; } interface Store { subscribe: (callback: () => void) => () => void; getState: () => StoreState; setState: <K extends keyof StoreState>(key: K, value: StoreState[K]) => void; setStateWithValidation: ( value: string, direction: NavigationDirection, ) => Promise<boolean>; hasValidation: () => boolean; notify: () => void; addStep: (value: string, completed: boolean, disabled: boolean) => void; removeStep: (value: string) => void; setStep: (value: string, completed: boolean, disabled: boolean) => void; } const StoreContext = React.createContext<Store | null>(null); function useStoreContext(consumerName: string) { const context = React.useContext(StoreContext); if (!context) { throw new Error(`\`${consumerName}\` must be used within \`${ROOT_NAME}\``); } return context; } function useStore<T>(selector: (state: StoreState) => T): T { const store = useStoreContext("useStore"); const getSnapshot = React.useCallback( () => selector(store.getState()), [store, selector], ); return React.useSyncExternalStore(store.subscribe, getSnapshot, getSnapshot); } interface ItemData { id: string; ref: React.RefObject<TriggerElement | null>; value: string; active: boolean; disabled: boolean; } interface StepperContextValue { rootId: string; dir: Direction; orientation: Orientation; activationMode: ActivationMode; disabled: boolean; nonInteractive: boolean; loop: boolean; } const StepperContext = React.createContext<StepperContextValue | null>(null); function useStepperContext(consumerName: string) { const context = React.useContext(StepperContext); if (!context) { throw new Error(`\`${consumerName}\` must be used within \`${ROOT_NAME}\``); } return context; } interface StepperProps extends DivProps { value?: string; defaultValue?: string; onValueChange?: (value: string) => void; onValueComplete?: (value: string, completed: boolean) => void; onValueAdd?: (value: string) => void; onValueRemove?: (value: string) => void; onValidate?: ( value: string, direction: NavigationDirection, ) => boolean | Promise<boolean>; activationMode?: ActivationMode; dir?: Direction; orientation?: Orientation; disabled?: boolean; loop?: boolean; nonInteractive?: boolean; } function Stepper(props: StepperProps) { const { value, defaultValue, onValueChange, onValueComplete, onValueAdd, onValueRemove, onValidate, dir: dirProp, orientation = "horizontal", activationMode = "automatic", asChild, disabled = false, nonInteractive = false, loop = false, className, id, ...rootProps } = props; const listenersRef = useLazyRef(() => new Set<() => void>()); const stateRef = useLazyRef<StoreState>(() => ({ steps: new Map(), value: value ?? defaultValue ?? "", })); const propsRef = useAsRef({ onValueChange, onValueComplete, onValueAdd, onValueRemove, onValidate, }); const store = React.useMemo<Store>(() => { return { subscribe: (cb) => { listenersRef.current.add(cb); return () => listenersRef.current.delete(cb); }, getState: () => stateRef.current, setState: (key, value) => { if (Object.is(stateRef.current[key], value)) return; if (key === "value" && typeof value === "string") { stateRef.current.value = value; propsRef.current.onValueChange?.(value); } else { stateRef.current[key] = value; } store.notify(); }, setStateWithValidation: async (value, direction) => { if (!propsRef.current.onValidate) { store.setState("value", value); return true; } try { const isValid = await propsRef.current.onValidate(value, direction); if (isValid) { store.setState("value", value); } return isValid; } catch { return false; } }, hasValidation: () => !!propsRef.current.onValidate, addStep: (value, completed, disabled) => { const newStep: StepState = { value, completed, disabled }; stateRef.current.steps.set(value, newStep); propsRef.current.onValueAdd?.(value); store.notify(); }, removeStep: (value) => { stateRef.current.steps.delete(value); propsRef.current.onValueRemove?.(value); store.notify(); }, setStep: (value, completed, disabled) => { const step = stateRef.current.steps.get(value); if (step) { const updatedStep: StepState = { ...step, completed, disabled }; stateRef.current.steps.set(value, updatedStep); if (completed !== step.completed) { propsRef.current.onValueComplete?.(value, completed); } store.notify(); } }, notify: () => { for (const cb of listenersRef.current) { cb(); } }, }; }, [listenersRef, stateRef, propsRef]); useIsomorphicLayoutEffect(() => { if (value !== undefined) { store.setState("value", value); } }, [value]); const dir = useDirection(dirProp); const instanceId = React.useId(); const rootId = id ?? instanceId; const contextValue = React.useMemo<StepperContextValue>( () => ({ rootId, dir, orientation, activationMode, disabled, nonInteractive, loop, }), [rootId, dir, orientation, activationMode, disabled, nonInteractive, loop], ); const RootPrimitive = asChild ? Slot : "div"; return ( <StoreContext.Provider value={store}> <StepperContext.Provider value={contextValue}> <RootPrimitive id={rootId} data-disabled={disabled ? "" : undefined} data-orientation={orientation} data-slot="stepper" dir={dir} {...rootProps} className={cn( "flex gap-1.5", orientation === "horizontal" ? "w-full flex-col" : "flex-row", className, )} /> </StepperContext.Provider> </StoreContext.Provider> ); } interface FocusContextValue { tabStopId: string | null; onItemFocus: (tabStopId: string) => void; onItemShiftTab: () => void; onFocusableItemAdd: () => void; onFocusableItemRemove: () => void; onItemRegister: (item: ItemData) => void; onItemUnregister: (id: string) => void; getItems: () => ItemData[]; } const FocusContext = React.createContext<FocusContextValue | null>(null); function useFocusContext(consumerName: string) { const context = React.useContext(FocusContext); if (!context) { throw new Error( `\`${consumerName}\` must be used within \`FocusProvider\``, ); } return context; } interface StepperListProps extends DivProps { asChild?: boolean; } function StepperList(props: StepperListProps) { const { asChild, onBlur: onBlurProp, onFocus: onFocusProp, onMouseDown: onMouseDownProp, className, children, ref, ...listProps } = props; const context = useStepperContext(LIST_NAME); const orientation = context.orientation; const currentValue = useStore((state) => state.value); const propsRef = useAsRef({ onBlur: onBlurProp, onFocus: onFocusProp, onMouseDown: onMouseDownProp, }); const [tabStopId, setTabStopId] = React.useState<string | null>(null); const [isTabbingBackOut, setIsTabbingBackOut] = React.useState(false); const [focusableItemCount, setFocusableItemCount] = React.useState(0); const isClickFocusRef = React.useRef(false); const itemsRef = React.useRef<Map<string, ItemData>>(new Map()); const listRef = React.useRef<ListElement>(null); const composedRef = useComposedRefs(ref, listRef); const onItemFocus = React.useCallback((tabStopId: string) => { setTabStopId(tabStopId); }, []); const onItemShiftTab = React.useCallback(() => { setIsTabbingBackOut(true); }, []); const onFocusableItemAdd = React.useCallback(() => { setFocusableItemCount((prevCount) => prevCount + 1); }, []); const onFocusableItemRemove = React.useCallback(() => { setFocusableItemCount((prevCount) => prevCount - 1); }, []); const onItemRegister = React.useCallback((item: ItemData) => { itemsRef.current.set(item.id, item); }, []); const onItemUnregister = React.useCallback((id: string) => { itemsRef.current.delete(id); }, []); const getItems = React.useCallback(() => { return Array.from(itemsRef.current.values()) .filter((item) => item.ref.current) .sort((a, b) => { const elementA = a.ref.current; const elementB = b.ref.current; if (!elementA || !elementB) return 0; const position = elementA.compareDocumentPosition(elementB); if (position & Node.DOCUMENT_POSITION_FOLLOWING) { return -1; } if (position & Node.DOCUMENT_POSITION_PRECEDING) { return 1; } return 0; }); }, []); const onBlur = React.useCallback( (event: React.FocusEvent<ListElement>) => { propsRef.current.onBlur?.(event); if (event.defaultPrevented) return; setIsTabbingBackOut(false); }, [propsRef], ); const onFocus = React.useCallback( (event: React.FocusEvent<ListElement>) => { propsRef.current.onFocus?.(event); if (event.defaultPrevented) return; const isKeyboardFocus = !isClickFocusRef.current; if ( event.target === event.currentTarget && isKeyboardFocus && !isTabbingBackOut ) { const entryFocusEvent = new CustomEvent(ENTRY_FOCUS, EVENT_OPTIONS); event.currentTarget.dispatchEvent(entryFocusEvent); if (!entryFocusEvent.defaultPrevented) { const items = Array.from(itemsRef.current.values()).filter( (item) => !item.disabled, ); const selectedItem = currentValue ? items.find((item) => item.value === currentValue) : undefined; const activeItem = items.find((item) => item.active); const currentItem = items.find((item) => item.id === tabStopId); const candidateItems = [ selectedItem, activeItem, currentItem, ...items, ].filter(Boolean) as ItemData[]; const candidateRefs = candidateItems.map((item) => item.ref); focusFirst(candidateRefs, false); } } isClickFocusRef.current = false; }, [propsRef, isTabbingBackOut, currentValue, tabStopId], ); const onMouseDown = React.useCallback( (event: React.MouseEvent<ListElement>) => { propsRef.current.onMouseDown?.(event); if (event.defaultPrevented) return; isClickFocusRef.current = true; }, [propsRef], ); const focusContextValue = React.useMemo<FocusContextValue>( () => ({ tabStopId, onItemFocus, onItemShiftTab, onFocusableItemAdd, onFocusableItemRemove, onItemRegister, onItemUnregister, getItems, }), [ tabStopId, onItemFocus, onItemShiftTab, onFocusableItemAdd, onFocusableItemRemove, onItemRegister, onItemUnregister, getItems, ], ); const ListPrimitive = asChild ? Slot : "div"; return ( <FocusContext.Provider value={focusContextValue}> <ListPrimitive role="tablist" aria-orientation={orientation} data-orientation={orientation} data-slot="stepper-list" dir={context.dir} tabIndex={isTabbingBackOut || focusableItemCount === 0 ? -1 : 0} {...listProps} ref={composedRef} className={cn( "flex outline-none", orientation === "horizontal" ? "flex-row items-center" : "flex-col items-start", className, )} onBlur={onBlur} onFocus={onFocus} onMouseDown={onMouseDown} > {children} </ListPrimitive> </FocusContext.Provider> ); } interface StepperItemContextValue { value: string; stepState: StepState | undefined; } const StepperItemContext = React.createContext<StepperItemContextValue | null>( null, ); function useStepperItemContext(consumerName: string) { const context = React.useContext(StepperItemContext); if (!context) { throw new Error(`\`${consumerName}\` must be used within \`${ITEM_NAME}\``); } return context; } interface StepperItemProps extends DivProps { value: string; completed?: boolean; disabled?: boolean; } function StepperItem(props: StepperItemProps) { const { value: itemValue, completed = false, disabled = false, asChild, className, children, ref, ...itemProps } = props; const context = useStepperContext(ITEM_NAME); const store = useStoreContext(ITEM_NAME); const orientation = context.orientation; const value = useStore((state) => state.value); useIsomorphicLayoutEffect(() => { store.addStep(itemValue, completed, disabled); return () => { store.removeStep(itemValue); }; }, [itemValue, completed, disabled]); useIsomorphicLayoutEffect(() => { store.setStep(itemValue, completed, disabled); }, [itemValue, completed, disabled]); const stepState = useStore((state) => state.steps.get(itemValue)); const steps = useStore((state) => state.steps); const dataState = getDataState(value, itemValue, stepState, steps); const itemContextValue = React.useMemo<StepperItemContextValue>( () => ({ value: itemValue, stepState, }), [itemValue, stepState], ); const ItemPrimitive = asChild ? Slot : "div"; return ( <StepperItemContext.Provider value={itemContextValue}> <ItemPrimitive data-disabled={stepState?.disabled ? "" : undefined} data-orientation={orientation} data-state={dataState} data-slot="stepper-item" dir={context.dir} {...itemProps} ref={ref} className={cn( "relative flex not-last:flex-1 items-center", orientation === "horizontal" ? "flex-row" : "flex-col", className, )} > {children} </ItemPrimitive> </StepperItemContext.Provider> ); } function StepperTrigger(props: ButtonProps) { const { asChild, onClick: onClickProp, onFocus: onFocusProp, onKeyDown: onKeyDownProp, onMouseDown: onMouseDownProp, disabled, className, ref, ...triggerProps } = props; const context = useStepperContext(TRIGGER_NAME); const itemContext = useStepperItemContext(TRIGGER_NAME); const itemValue = itemContext.value; const store = useStoreContext(TRIGGER_NAME); const focusContext = useFocusContext(TRIGGER_NAME); const value = useStore((state) => state.value); const steps = useStore((state) => state.steps); const stepState = useStore((state) => state.steps.get(itemValue)); const propsRef = useAsRef({ onClick: onClickProp, onFocus: onFocusProp, onKeyDown: onKeyDownProp, onMouseDown: onMouseDownProp, }); const activationMode = context.activationMode; const orientation = context.orientation; const loop = context.loop; const stepIndex = Array.from(steps.keys()).indexOf(itemValue); const stepPosition = stepIndex + 1; const stepCount = steps.size; const triggerId = getId(context.rootId, "trigger", itemValue); const contentId = getId(context.rootId, "content", itemValue); const titleId = getId(context.rootId, "title", itemValue); const descriptionId = getId(context.rootId, "description", itemValue); const isDisabled = disabled || stepState?.disabled || context.disabled; const isActive = value === itemValue; const isTabStop = focusContext.tabStopId === triggerId; const dataState = getDataState(value, itemValue, stepState, steps); const triggerRef = React.useRef<TriggerElement>(null); const composedRef = useComposedRefs(ref, triggerRef); const isArrowKeyPressedRef = React.useRef(false); const isMouseClickRef = React.useRef(false); React.useEffect(() => { function onKeyDown(event: KeyboardEvent) { if (ARROW_KEYS.includes(event.key)) { isArrowKeyPressedRef.current = true; } } function onKeyUp() { isArrowKeyPressedRef.current = false; } document.addEventListener("keydown", onKeyDown); document.addEventListener("keyup", onKeyUp); return () => { document.removeEventListener("keydown", onKeyDown); document.removeEventListener("keyup", onKeyUp); }; }, []); useIsomorphicLayoutEffect(() => { focusContext.onItemRegister({ id: triggerId, ref: triggerRef, value: itemValue, active: isTabStop, disabled: !!isDisabled, }); if (!isDisabled) { focusContext.onFocusableItemAdd(); } return () => { focusContext.onItemUnregister(triggerId); if (!isDisabled) { focusContext.onFocusableItemRemove(); } }; }, [focusContext, triggerId, itemValue, isTabStop, isDisabled]); const onClick = React.useCallback( async (event: React.MouseEvent<TriggerElement>) => { propsRef.current.onClick?.(event); if (event.defaultPrevented) return; if (!isDisabled && !context.nonInteractive) { const currentStepIndex = Array.from(steps.keys()).indexOf(value ?? ""); const targetStepIndex = Array.from(steps.keys()).indexOf(itemValue); const direction = targetStepIndex > currentStepIndex ? "next" : "prev"; await store.setStateWithValidation(itemValue, direction); } }, [ isDisabled, context.nonInteractive, store, itemValue, value, steps, propsRef, ], ); const onFocus = React.useCallback( async (event: React.FocusEvent<TriggerElement>) => { propsRef.current.onFocus?.(event); if (event.defaultPrevented) return; focusContext.onItemFocus(triggerId); const isKeyboardFocus = !isMouseClickRef.current; if ( !isActive && !isDisabled && activationMode !== "manual" && !context.nonInteractive && isKeyboardFocus ) { const currentStepIndex = Array.from(steps.keys()).indexOf(value || ""); const targetStepIndex = Array.from(steps.keys()).indexOf(itemValue); const direction = targetStepIndex > currentStepIndex ? "next" : "prev"; await store.setStateWithValidation(itemValue, direction); } isMouseClickRef.current = false; }, [ focusContext, triggerId, activationMode, isActive, isDisabled, context.nonInteractive, store, itemValue, value, steps, propsRef, ], ); const onKeyDown = React.useCallback( async (event: React.KeyboardEvent<TriggerElement>) => { propsRef.current.onKeyDown?.(event); if (event.defaultPrevented) return; if (event.key === "Enter" && context.nonInteractive) { event.preventDefault(); return; } if ( (event.key === "Enter" || event.key === " ") && activationMode === "manual" && !context.nonInteractive ) { event.preventDefault(); if (!isDisabled && triggerRef.current) { triggerRef.current.click(); } return; } if (event.key === "Tab" && event.shiftKey) { focusContext.onItemShiftTab(); return; } if (event.target !== event.currentTarget) return; const focusIntent = getFocusIntent(event, context.dir, orientation); if (focusIntent !== undefined) { if (event.metaKey || event.ctrlKey || event.altKey || event.shiftKey) return; event.preventDefault(); const items = focusContext.getItems().filter((item) => !item.disabled); let candidateRefs = items.map((item) => item.ref); if (focusIntent === "last") { candidateRefs.reverse(); } else if (focusIntent === "prev" || focusIntent === "next") { if (focusIntent === "prev") candidateRefs.reverse(); const currentIndex = candidateRefs.findIndex( (ref) => ref.current === event.currentTarget, ); candidateRefs = loop ? wrapArray(candidateRefs, currentIndex + 1) : candidateRefs.slice(currentIndex + 1); } if (store.hasValidation() && candidateRefs.length > 0) { const nextRef = candidateRefs[0]; const nextElement = nextRef?.current; const nextItem = items.find( (item) => item.ref.current === nextElement, ); if (nextItem && nextItem.value !== itemValue) { const currentStepIndex = Array.from(steps.keys()).indexOf( value || "", ); const targetStepIndex = Array.from(steps.keys()).indexOf( nextItem.value, ); const direction: NavigationDirection = targetStepIndex > currentStepIndex ? "next" : "prev"; if (direction === "next") { const isValid = await store.setStateWithValidation( nextItem.value, direction, ); if (!isValid) return; } else { store.setState("value", nextItem.value); } queueMicrotask(() => nextElement?.focus()); return; } } queueMicrotask(() => focusFirst(candidateRefs)); } }, [ focusContext, context.nonInteractive, context.dir, activationMode, orientation, loop, isDisabled, store, propsRef, itemValue, value, steps, ], ); const onMouseDown = React.useCallback( (event: React.MouseEvent<TriggerElement>) => { propsRef.current.onMouseDown?.(event); if (event.defaultPrevented) return; isMouseClickRef.current = true; if (isDisabled) { event.preventDefault(); } else { focusContext.onItemFocus(triggerId); } }, [focusContext, triggerId, isDisabled, propsRef], ); const TriggerPrimitive = asChild ? Slot : "button"; return ( <TriggerPrimitive id={triggerId} role="tab" type="button" aria-controls={contentId} aria-current={isActive ? "step" : undefined} aria-describedby={`${titleId} ${descriptionId}`} aria-posinset={stepPosition} aria-selected={isActive} aria-setsize={stepCount} data-disabled={isDisabled ? "" : undefined} data-state={dataState} data-slot="stepper-trigger" disabled={isDisabled} tabIndex={isTabStop ? 0 : -1} {...triggerProps} ref={composedRef} className={cn( "inline-flex items-center justify-center gap-1 rounded-md text-left outline-none transition-all cursor-pointer", "focus-visible:border-accent-8 focus-visible:ring-[3px] focus-visible:ring-accent-a8", "disabled:pointer-events-none disabled:opacity-50 disabled:cursor-not-allowed", "aria-invalid:border-danger aria-invalid:ring-danger/20", "[&_svg:not([class*='size-'])]:size-2 [&_svg]:pointer-events-none [&_svg]:shrink-0", "not-has-data-[slot=description]:rounded-full not-has-data-[slot=title]:rounded-full", className, )} onClick={onClick} onFocus={onFocus} onKeyDown={onKeyDown} onMouseDown={onMouseDown} /> ); } interface StepperIndicatorProps extends Omit<DivProps, "children"> { children?: React.ReactNode | ((dataState: DataState) => React.ReactNode); } function StepperIndicator(props: StepperIndicatorProps) { const { className, children, asChild, ref, ...indicatorProps } = props; const context = useStepperContext(INDICATOR_NAME); const itemContext = useStepperItemContext(INDICATOR_NAME); const value = useStore((state) => state.value); const itemValue = itemContext.value; const stepState = useStore((state) => state.steps.get(itemValue)); const steps = useStore((state) => state.steps); const stepPosition = Array.from(steps.keys()).indexOf(itemValue) + 1; const dataState = getDataState(value, itemValue, stepState, steps); const IndicatorPrimitive = asChild ? Slot : "div"; return ( <IndicatorPrimitive data-state={dataState} data-slot="stepper-indicator" dir={context.dir} {...indicatorProps} ref={ref} className={cn( "flex size-3 shrink-0 items-center justify-center rounded-full border-2 font-medium transition-colors", "border-gray-7 bg-gray-2 text-gray-11", "data-[state=active]:border-accent-8 data-[state=active]:bg-accent-9 data-[state=active]:text-accent-contrast", "data-[state=completed]:border-accent-8 data-[state=completed]:bg-accent-9 data-[state=completed]:text-accent-contrast", className, )} > {typeof children === "function" ? ( children(dataState) ) : children ? ( children ) : dataState === "completed" ? ( <CheckIcon className="icon" /> ) : ( stepPosition )} </IndicatorPrimitive> ); } interface StepperSeparatorProps extends DivProps { forceMount?: boolean; } function StepperSeparator(props: StepperSeparatorProps) { const { className, asChild, forceMount = false, ref, ...separatorProps } = props; const context = useStepperContext(SEPARATOR_NAME); const itemContext = useStepperItemContext(SEPARATOR_NAME); const value = useStore((state) => state.value); const steps = useStore((state) => state.steps); const orientation = context.orientation; const stepIndex = Array.from(steps.keys()).indexOf(itemContext.value); const isLastStep = stepIndex === steps.size - 1; if (isLastStep && !forceMount) return null; const dataState = getDataState( value, itemContext.value, itemContext.stepState, steps, "separator", ); const SeparatorPrimitive = asChild ? Slot : "div"; return ( <SeparatorPrimitive role="separator" aria-hidden="true" aria-orientation={orientation} data-orientation={orientation} data-state={dataState} data-slot="stepper-separator" dir={context.dir} {...separatorProps} ref={ref} className={cn( "bg-gray-6 transition-colors mx-1", "data-[state=active]:bg-accent-8 data-[state=completed]:bg-accent-8", orientation === "horizontal" ? "h-px flex-1" : "h-10 w-px", className, )} /> ); } interface StepperTitleProps extends React.ComponentProps<"span"> { asChild?: boolean; } function StepperTitle(props: StepperTitleProps) { const { className, asChild, ref, ...titleProps } = props; const context = useStepperContext(TITLE_NAME); const itemContext = useStepperItemContext(TITLE_NAME); const titleId = getId(context.rootId, "title", itemContext.value); const TitlePrimitive = asChild ? Slot : "span"; return ( <TitlePrimitive id={titleId} data-slot="title" dir={context.dir} {...titleProps} ref={ref} className={cn("font-medium text-gray-12", className)} /> ); } interface StepperDescriptionProps extends React.ComponentProps<"span"> { asChild?: boolean; } function StepperDescription(props: StepperDescriptionProps) { const { className, asChild, ref, ...descriptionProps } = props; const context = useStepperContext(DESCRIPTION_NAME); const itemContext = useStepperItemContext(DESCRIPTION_NAME); const descriptionId = getId(context.rootId, "description", itemContext.value); const DescriptionPrimitive = asChild ? Slot : "span"; return ( <DescriptionPrimitive id={descriptionId} data-slot="description" dir={context.dir} {...descriptionProps} ref={ref} className={cn("text-gray-11", className)} /> ); } interface StepperContentProps extends DivProps { value: string; forceMount?: boolean; } function StepperContent(props: StepperContentProps) { const { value: valueProp, asChild, forceMount = false, ref, className, ...contentProps } = props; const context = useStepperContext(CONTENT_NAME); const value = useStore((state) => state.value); const contentId = getId(context.rootId, "content", valueProp); const triggerId = getId(context.rootId, "trigger", valueProp); if (valueProp !== value && !forceMount) return null; const ContentPrimitive = asChild ? Slot : "div"; return ( <ContentPrimitive id={contentId} role="tabpanel" aria-labelledby={triggerId} data-slot="stepper-content" dir={context.dir} {...contentProps} ref={ref} className={cn("flex-1 outline-none", className)} /> ); } function StepperPrev(props: ButtonProps) { const { asChild, onClick: onClickProp, disabled, ...prevProps } = props; const store = useStoreContext(PREV_NAME); const value = useStore((state) => state.value); const steps = useStore((state) => state.steps); const propsRef = useAsRef({ onClick: onClickProp, }); const stepKeys = Array.from(steps.keys()); const currentIndex = value ? stepKeys.indexOf(value) : -1; const isDisabled = disabled || currentIndex <= 0; const onClick = React.useCallback( async (event: React.MouseEvent<HTMLButtonElement>) => { propsRef.current.onClick?.(event); if (event.defaultPrevented || isDisabled) return; const prevIndex = Math.max(currentIndex - 1, 0); const prevStepValue = stepKeys[prevIndex]; if (prevStepValue) { store.setState("value", prevStepValue); } }, [propsRef, isDisabled, currentIndex, stepKeys, store], ); const PrevPrimitive = asChild ? Slot : "button"; return ( <PrevPrimitive type="button" data-slot="stepper-prev" disabled={isDisabled} {...prevProps} onClick={onClick} /> ); } function StepperNext(props: ButtonProps) { const { asChild, onClick: onClickProp, disabled, ...nextProps } = props; const store = useStoreContext(NEXT_NAME); const value = useStore((state) => state.value); const steps = useStore((state) => state.steps); const propsRef = useAsRef({ onClick: onClickProp, }); const stepKeys = Array.from(steps.keys()); const currentIndex = value ? stepKeys.indexOf(value) : -1; const isDisabled = disabled || currentIndex >= stepKeys.length - 1; const onClick = React.useCallback( async (event: React.MouseEvent<HTMLButtonElement>) => { propsRef.current.onClick?.(event); if (event.defaultPrevented || isDisabled) return; const nextIndex = Math.min(currentIndex + 1, stepKeys.length - 1); const nextStepValue = stepKeys[nextIndex]; if (nextStepValue) { await store.setStateWithValidation(nextStepValue, "next"); } }, [propsRef, isDisabled, currentIndex, stepKeys, store], ); const NextPrimitive = asChild ? Slot : "button"; return ( <NextPrimitive type="button" data-slot="stepper-next" disabled={isDisabled} {...nextProps} onClick={onClick} /> ); } export { Stepper, StepperList, StepperItem, StepperTrigger, StepperIndicator, StepperSeparator, StepperTitle, StepperDescription, StepperContent, StepperPrev, StepperNext, useStore as useStepper, type StepperProps, }; ``` </Step> </Steps> # Swap (/docs/components/swap) ## Preview [#preview] <ComponentPreview name="swap-demo" description="Switches between two views in place."> ```tsx import { Swap } from "@/components/ui/Swap"; export function SwapDemo() { return ( <Swap> <div className="flex h-8 items-center rounded-sm bg-accent-3 px-1">Color scale</div> <div className="flex h-8 items-center rounded-sm bg-gray-3 px-1">Type scale</div> </Swap> ) } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/swap ``` ### Manual [#manual] <Steps> <Step> Copy and paste the button component into your `components/ui/Button.tsx` file. ```tsx /** * @description Displays a button or a component that looks like a button. / import as React from "react"; import { Slot } from "@radix-ui/react-slot"; import { cva, type VariantProps } from "class-variance-authority"; import { cn } from "@/utils/class-names"; import { Spinner } from "@/components/ui/Spinner"; const buttonVariants = cva("button", { variants: { variant: { default: "button-fill", fill: "button-fill", pill: "button-pill border border-gray-6 text-gray-11 bg-gray-2 hover:bg-gray-3", link: "button-link", menu: "button-menu", }, size: { default: "h-4", xs: "h-2.5", sm: "h-3", md: "h-4", lg: "h-5", xl: "h-6", icon: "w-3 h-3 p-0", "icon-md": "w-4 h-4 p-0", }, }, defaultVariants: { variant: "default", size: "default", }, }); interface ButtonProps extends React.ComponentProps<"button">, VariantProps<typeof buttonVariants> { asChild?: boolean; isDisabled?: boolean; isLoading?: boolean; isLoadingText?: string | React.ReactNode; mode?: VariantProps<typeof buttonVariants>["variant"]; label?: string | React.ReactNode; } const Button = React.forwardRef<HTMLButtonElement, ButtonProps>( (props: ButtonProps, ref) => { const { className, variant, mode, size, asChild = false, isDisabled, isLoading, isLoadingText, children, label, ...rest } = props; const Comp = asChild ? Slot : "button"; const disabled = isDisabled || isLoading || props.disabled; const effectiveVariant = variant ?? mode; return ( <Comp data-slot="button" className={cn( buttonVariants({ variant: effectiveVariant, size, className }), disabled && "opacity-50 cursor-not-allowed" )} ref={ref} disabled={disabled} {...rest} > {asChild ? ( children ) : ( <> {isLoading && isLoadingText ? ( isLoadingText ) : ( <> {isLoading ? <Spinner /> : null} {label} {children} </> )} </> )} </Comp> ); } ); Button.displayName = "Button"; export { Button, buttonVariants }; export type { ButtonProps }; export default Button; ``` </Step> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the Swap component into your `components/ui/Swap.tsx` file. ```tsx "use client"; import * as React from "react"; import { cn } from "@/utils/class-names"; import { Button } from "@/components/ui/Button"; function Swap({ className, children, label = "Swap", }: { className?: string; children: React.ReactNode; label?: string; }) { const items = React.Children.toArray(children); const [index, setIndex] = React.useState(0); const current = items.length ? index % items.length : 0; return ( <div data-slot="swap" className={cn("flex flex-col items-start gap-0.5", className)}> <div className="relative min-h-8 w-full"> {items.map((item, itemIndex) => ( <div key={itemIndex} className={cn( "transition duration-300 motion-reduce:transition-none", itemIndex === current ? "opacity-100" : "pointer-events-none absolute inset-0 opacity-0", )} aria-hidden={itemIndex === current ? undefined : true} > {item} </div> ))} </div> <Button type="button" variant="pill" size="sm" aria-label={label} onClick={() => setIndex((value) => (items.length ? (value + 1) % items.length : 0))} > {label} </Button> </div> ); } export { Swap }; ``` </Step> </Steps> # Switch (/docs/components/switch) ## Preview [#preview] <ComponentPreview name="switch-demo" description="A control that allows the user to toggle between on and off states."> ```tsx import { useState } from "react"; import { Switch } from "@/components/ui/Switch"; export function SwitchDemo() { const [checked, setChecked] = useState(false); return ( <div className="flex items-center gap-2"> <Switch id="default" checked={checked} onCheckedChange={setChecked} /> <label htmlFor="default" className="text-sm font-medium leading-none cursor-pointer" > Airplane Mode </label> </div> ); } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/switch ``` ### Manual [#manual] <Steps> <Step> Install the following dependencies: ```bash pnpm install radix-ui ``` </Step> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the Switch component into your `components/ui/Switch.tsx` file. ```tsx "use client"; /** * @description A control that allows the user to toggle between on and off states. / import as React from "react"; import { Switch as SwitchPrimitive } from "radix-ui"; import { cn } from "@/utils/class-names"; function Switch({ className, ...props }: React.ComponentProps<typeof SwitchPrimitive.Root>) { return ( <SwitchPrimitive.Root data-slot="switch" className={cn( "relative h-1.5 w-2.5 cursor-pointer rounded-full outline-none bg-accent-4 data-[state=checked]:bg-accent-10 border border-gray-a6 hover:bg-accent-5", className )} {...props} > <SwitchThumb /> </SwitchPrimitive.Root> ); } function SwitchThumb({ className, ...props }: React.ComponentProps<typeof SwitchPrimitive.Thumb>) { return ( <SwitchPrimitive.Thumb data-slot="switch-thumb" className={cn( "block size-1 translate-x-[3.5px] rounded-full bg-gray-1 shadow-md transition-transform duration-100 will-change-transform data-[state=checked]:translate-x-[15.5px]", className )} {...props} /> ); } export { Switch, SwitchThumb }; ``` </Step> </Steps> ## Usage [#usage] ### Checked [#checked] ```tsx export const Checked = () => ( <div className="flex items-center gap-2"> <Switch id="checked" defaultChecked /> <label htmlFor="checked" className="text-sm font-medium leading-none cursor-pointer" > Bluetooth </label> </div> ) ``` ### Unchecked [#unchecked] ```tsx export const Unchecked = () => ( <div className="flex items-center gap-2"> <Switch id="unchecked" /> <label htmlFor="unchecked" className="text-sm font-medium leading-none cursor-pointer" > Wi-Fi </label> </div> ) ``` ### Disabled [#disabled] ```tsx export const Disabled = () => ( <div className="flex flex-col gap-2"> <div className="flex items-center gap-2"> <Switch id="disabled-unchecked" disabled /> <label htmlFor="disabled-unchecked" className="text-sm font-medium leading-none text-gray-a8 cursor-not-allowed" > Disabled unchecked </label> </div> <div className="flex items-center gap-2"> <Switch id="disabled-checked" disabled defaultChecked /> <label htmlFor="disabled-checked" className="text-sm font-medium leading-none text-gray-a8 cursor-not-allowed" > Disabled checked </label> </div> </div> ) ``` ### WithDescription [#withdescription] ```tsx export const WithDescription = () => { const [checked, setChecked] = useState(false); return ( <div className="flex items-start gap-2"> <Switch id="with-description" checked={checked} onCheckedChange={setChecked} className="mt-0.5" /> <div className="flex flex-col gap-1"> <label htmlFor="with-description" className="text-sm font-medium leading-none cursor-pointer" > Marketing emails </label> <p className="text-sm text-gray-a11 m-0"> Receive emails about new products, features, and more. </p> </div> </div> ); }; ``` ### SwitchGroup [#switchgroup] ```tsx export const SwitchGroup = () => { const [settings, setSettings] = useState({ notifications: true, marketing: false, security: true, updates: false, }); const items = [ { id: "notifications", label: "Push Notifications", description: "Receive push notifications on your device", }, { id: "marketing", label: "Marketing Emails", description: "Receive emails about new products and features", }, { id: "security", label: "Two-Factor Authentication", description: "Enable two-factor authentication for your account", }, { id: "updates", label: "Automatic Updates", description: "Automatically install software updates", }, ]; const handleCheckedChange = ( key: keyof typeof settings, checked: boolean ) => { setSettings((prev) => ({ ...prev, [key]: checked })); }; return ( <div className="flex flex-col gap-4"> <div className="text-sm font-semibold">System Settings:</div> {items.map((item) => ( <div key={item.id} className="flex items-start gap-2"> <Switch id={item.id} checked={settings[item.id as keyof typeof settings]} onCheckedChange={(checked) => handleCheckedChange(item.id as keyof typeof settings, checked) } className="mt-0.5" /> <div className="flex flex-col gap-1"> <label htmlFor={item.id} className="text-sm font-medium leading-none cursor-pointer" > {item.label} </label> <p className="text-sm text-gray-a11 m-0">{item.description}</p> </div> </div> ))} <div className="mt-2 text-sm text-gray-a11"> Active settings: {Object.values(settings).filter(Boolean).length} </div> </div> ); }; ``` # Table (/docs/components/table) ## Preview [#preview] <ComponentPreview name="table-demo" description="A responsive table for organizing related data into rows and columns."> ```tsx import { ResponsiveTableCard, Table, TableBody, TableCaption, TableCell, TableHead, TableHeader, TableRow, } from "@/components/ui/Table" const headers = [ { id: "component", header: "Component" }, { id: "status", header: "Status" }, { id: "checks", header: "Checks" }, ] const rows = [ { id: "badge", cells: [ { id: "badge-component", content: "Badge" }, { id: "badge-status", content: "Ready" }, { id: "badge-checks", content: "12" }, ], }, { id: "input", cells: [ { id: "input-component", content: "Input" }, { id: "input-status", content: "In review" }, { id: "input-checks", content: "8" }, ], }, { id: "textarea", cells: [ { id: "textarea-component", content: "Textarea" }, { id: "textarea-status", content: "Ready" }, { id: "textarea-checks", content: "10" }, ], }, ] export function TableDemo() { return ( <div className="w-full"> <ResponsiveTableCard headers={headers} rows={rows} /> <Table> <TableCaption>Recent Aura component reviews.</TableCaption> <TableHeader> <TableRow> <TableHead>Component</TableHead> <TableHead>Status</TableHead> <TableHead className="text-right">Checks</TableHead> </TableRow> </TableHeader> <TableBody> <TableRow> <TableCell>Badge</TableCell> <TableCell>Ready</TableCell> <TableCell className="text-right">12</TableCell> </TableRow> <TableRow> <TableCell>Input</TableCell> <TableCell>In review</TableCell> <TableCell className="text-right">8</TableCell> </TableRow> <TableRow> <TableCell>Textarea</TableCell> <TableCell>Ready</TableCell> <TableCell className="text-right">10</TableCell> </TableRow> </TableBody> </Table> </div> ) } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/table ``` ### Manual [#manual] <Steps> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the Table component into your `components/ui/Table.tsx` file. ```tsx "use client" import * as React from "react" import { cn } from "@/utils/class-names" function Table({ className, ...props }: React.ComponentProps<"table">) { return ( <div data-slot="table-container" className="relative w-full min-w-0 max-w-full overflow-x-auto border-gray-a6" > <table data-slot="table" className={cn("w-full caption-bottom text-sm hidden md:table", className)} {...props} /> </div> ) } function TableHeader({ className, ...props }: React.ComponentProps<"thead">) { return ( <thead data-slot="table-header" className={cn("[&_tr]:border-b border-gray-a6", className)} {...props} /> ) } function TableBody({ className, ...props }: React.ComponentProps<"tbody">) { return ( <tbody data-slot="table-body" className={cn("[&_tr:last-child]:border-0 ", className)} {...props} /> ) } function TableFooter({ className, ...props }: React.ComponentProps<"tfoot">) { return ( <tfoot data-slot="table-footer" className={cn( "bg-gray-2 border-t border-gray-a6 font-medium [&>tr]:last:border-b-0", className )} {...props} /> ) } function TableRow({ className, ...props }: React.ComponentProps<"tr">) { return ( <tr data-slot="table-row" className={cn( "hover:bg-gray-3 data-[state=selected]:bg-gray-4 border-b border-gray-a6 transition-colors", className )} {...props} /> ) } function TableHead({ className, ...props }: React.ComponentProps<"th">) { return ( <th data-slot="table-head" className={cn( "text-gray-11 h-3 px-1 text-left align-middle font-medium whitespace-nowrap [&:has([role=checkbox])]:pr-0 [&>[role=checkbox]]:translate-y-[2px] border-gray-a6", className )} {...props} /> ) } function TableCell({ className, ...props }: React.ComponentProps<"td">) { return ( <td data-slot="table-cell" className={cn( "p-1 align-middle whitespace-nowrap [&:has([role=checkbox])]:pr-0 [&>[role=checkbox]]:translate-y-[2px] border-gray-a6", className )} {...props} /> ) } function TableCaption({ className, ...props }: React.ComponentProps<"caption">) { return ( <caption data-slot="table-caption" className={cn("text-gray-11 mt-2 text-sm", className)} {...props} /> ) } /** * Responsive table card layout for mobile screens * Displays table data as cards on screens smaller than medium / interface ResponsiveTableCardProps { headers: Array<{ id: string; header: React.ReactNode; }>; rows: Array<{ id: string; cells: Array<{ id: string; content: React.ReactNode; }>; prefixContent?: React.ReactNode; }>; isLoading?: boolean; emptyState?: React.ReactNode; className?: string; } function ResponsiveTableCard({ headers, rows, isLoading = false, emptyState, className, }: ResponsiveTableCardProps) { if (isLoading) { return ( <div className={cn("md:hidden space-y-2", className)}> {Array.from({ length: 3 }).map((_, i) => ( <div key={i} className="bg-gray-2 border border-gray-6 rounded-md p-2 animate-pulse" > <div className="h-4 bg-gray-4 rounded w-3/4 mb-2" /> <div className="h-3 bg-gray-4 rounded w-1/2" /> </div> ))} </div> ); } if (rows.length === 0) { return ( <div className={cn("md:hidden", className)}> {emptyState || <div className="text-center py-8 text-gray-11">No hay resultados</div>} </div> ); } return ( <div className={cn("md:hidden space-y-2", className)}> {rows.map((row) => ( <div key={row.id} className="bg-gray-2 border border-gray-6 rounded-md p-2 space-y-1.5" > {row.prefixContent && ( <div> {row.prefixContent} </div> )} {row.cells.map((cell, cellIndex) => { const header = headers[cellIndex]; // Skip empty header columns (like actions column header) if (!header || (!header.header && header.id === "actions")) { return ( <div key={cell.id} className="flex justify-end pt-1"> {cell.content} </div> ); } return ( <div key={cell.id} className="flex flex-col gap-0.5"> <div className="text-gray-11 text-xs font-medium"> {header.header} </div> <div className="text-gray-12 text-sm"> {cell.content} </div> </div> ); })} </div> ))} </div> ); } export { Table, TableHeader, TableBody, TableFooter, TableHead, TableRow, TableCell, TableCaption, ResponsiveTableCard, } ``` </Step> </Steps> # Tabs (/docs/components/tabs) ## Preview [#preview] <ComponentPreview name="tabs-demo" description="A tabs component that allows the user to switch between different views."> ```tsx import { Tabs, TabsList, TabsTrigger, TabsContent, } from "@/components/ui/Tabs"; export function TabsDemo() { return ( <Tabs defaultValue="account" className="w-full"> <TabsList> <TabsTrigger value="account">Account</TabsTrigger> <TabsTrigger value="password">Password</TabsTrigger> </TabsList> <TabsContent value="account"> Make changes to your account here. </TabsContent> <TabsContent value="password"> Change your password here. </TabsContent> </Tabs> ); } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/tabs ``` ### Manual [#manual] <Steps> <Step> Install the following dependencies: ```bash pnpm install radix-ui ``` </Step> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the Tabs component into your `components/ui/Tabs.tsx` file. ```tsx "use client" import as React from "react" import {Tabs as TabsPrimitive} from "radix-ui" import { cn } from "@/utils/class-names" function Tabs({ className, ...props }: React.ComponentProps<typeof TabsPrimitive.Root>) { return ( <TabsPrimitive.Root data-slot="tabs" className={cn("flex flex-col gap-0.5", className)} {...props} /> ) } function TabsList({ className, ...props }: React.ComponentProps<typeof TabsPrimitive.List>) { return ( <TabsPrimitive.List data-slot="tabs-list" className={cn( "border-b border-gray-a6 text-gray-11 inline-flex h-3 w-fit items-center justify-center", className )} {...props} /> ) } function TabsTrigger({ className, ...props }: React.ComponentProps<typeof TabsPrimitive.Trigger>) { return ( <TabsPrimitive.Trigger data-slot="tabs-trigger" className={cn( "text-gray-10 data-[state=active]:text-gray-11 hover:text-gray-11 hover:bg-gray-a2 cursor-pointer inline-flex h-[calc(100%+1px)] flex-1 items-center justify-center gap-0.5 px-1 py-1 whitespace-nowrap data-[state=active]:border-b-gray-a6 data-[state=active]:border-b-2 border-b-transparent", className )} {...props} /> ) } function TabsContent({ className, ...props }: React.ComponentProps<typeof TabsPrimitive.Content>) { return ( <TabsPrimitive.Content data-slot="tabs-content" className={cn("flex-1 outline-none", className)} {...props} /> ) } export { Tabs, TabsList, TabsTrigger, TabsContent } ``` </Step> </Steps> # Tags Input (/docs/components/tags-input) ## Preview [#preview] <ComponentPreview name="tags-input-demo" description="A field that collects tags. Enter adds one, Backspace removes the last."> ```tsx import { TagsInput } from "@/components/ui/TagsInput"; export function TagsInputDemo() { return <TagsInput defaultValue={["Design", "Tokens"]} />; } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/tags-input ``` ### Manual [#manual] <Steps> <Step> Install the following dependencies: ```bash pnpm install @radix-ui/react-icons ``` </Step> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the TagsInput component into your `components/ui/TagsInput.tsx` file. ```tsx "use client"; import * as React from "react"; import { Cross2Icon } from "@radix-ui/react-icons"; import { cn } from "@/utils/class-names"; function TagsInput({ className, value, defaultValue = [], onValueChange, label = "Tags", placeholder = "Add a tag", }: { className?: string; value?: string[]; defaultValue?: string[]; onValueChange?: (value: string[]) => void; label?: string; placeholder?: string; }) { const [uncontrolled, setUncontrolled] = React.useState(defaultValue); const [draft, setDraft] = React.useState(""); const tags = value ?? uncontrolled; const id = React.useId(); const commit = (next: string[]) => { if (value === undefined) setUncontrolled(next); onValueChange?.(next); }; const add = (raw: string) => { const next = raw.trim(); if (!next || tags.includes(next)) return; commit([...tags, next]); setDraft(""); }; return ( <div data-slot="tags-input" className={cn("flex w-full max-w-xl flex-col gap-0.5", className)}> <label htmlFor={id}>{label}</label> <div className="flex flex-wrap items-center gap-0.5 rounded-sm border border-gray-7 bg-gray-1 p-0.5"> {tags.map((tag) => ( <span key={tag} className="inline-flex items-center gap-0.5 rounded-full bg-gray-3 px-1 py-0.5"> {tag} <button type="button" aria-label={`Remove ${tag}`} className="inline-flex size-2 items-center justify-center rounded-full hover:bg-gray-5 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent-8" onClick={() => commit(tags.filter((item) => item !== tag))} > <Cross2Icon className="icon" /> </button> </span> ))} <input id={id} value={draft} placeholder={placeholder} className="min-w-16 flex-1 border-0 bg-transparent px-0.5 py-0.5 text-gray-12 focus-visible:outline-none" onChange={(event) => setDraft(event.target.value)} onKeyDown={(event) => { if (event.key === "Enter" || event.key === ",") { event.preventDefault(); add(draft); } else if (event.key === "Backspace" && draft === "" && tags.length) { commit(tags.slice(0, -1)); } }} onBlur={() => add(draft)} /> </div> </div> ); } export { TagsInput }; ``` </Step> </Steps> # Textarea (/docs/components/textarea) ## Preview [#preview] <ComponentPreview name="textarea-demo" description="A multi-line text input for longer form content."> ```tsx import { Textarea } from "@/components/ui/Textarea" export function TextareaDemo() { return ( <Textarea aria-label="Review notes" placeholder="Add notes for the component review..." /> ) } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/textarea ``` ### Manual [#manual] <Steps> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the Textarea component into your `components/ui/Textarea.tsx` file. ```tsx /** * @description Multi-line text input. / import as React from "react"; import { cn } from "@/utils/class-names"; const Textarea = React.forwardRef< HTMLTextAreaElement, React.ComponentProps<"textarea"> >(({ className, ...props }, ref) => { return ( <textarea data-slot="textarea" ref={ref} className={cn( "flex min-h-20 w-full rounded-md border border-gray-6 bg-gray-1 px-2 py-1.5 text-gray-12 placeholder:text-gray-11 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-gray-8 disabled:cursor-not-allowed disabled:opacity-50", className, )} {...props} /> ); }); Textarea.displayName = "Textarea"; export { Textarea }; ``` </Step> </Steps> # Time Picker (/docs/components/time-picker) ## Preview [#preview] <ComponentPreview name="time-picker-demo" description="A clock dial paired with a typed time field."> ```tsx import { TimePicker } from "@/components/ui/TimePicker"; export function TimePickerDemo() { return <TimePicker defaultValue="09:30" />; } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/time-picker ``` ### Manual [#manual] <Steps> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the TimePicker component into your `components/ui/TimePicker.tsx` file. ```tsx "use client"; import * as React from "react"; import { cn } from "@/utils/class-names"; type TimeValue = { hour: number; minute: number; }; function pad(value: number) { return String(value).padStart(2, "0"); } function parseTime(value: string): TimeValue | null { const match = /^(\d{1,2}):(\d{2})$/.exec(value.trim()); if (!match) return null; const hour = Number(match[1]); const minute = Number(match[2]); if (hour > 23 || minute > 59) return null; return { hour, minute }; } function formatTime(value: TimeValue) { return `${pad(value.hour)}:${pad(value.minute)}`; } function TimePicker({ className, value, defaultValue = "09:30", onValueChange, label = "Time", }: { className?: string; value?: string; defaultValue?: string; onValueChange?: (value: string) => void; label?: string; }) { const parsedDefault = parseTime(defaultValue) ?? { hour: 9, minute: 30 }; const [uncontrolled, setUncontrolled] = React.useState(parsedDefault); const [text, setText] = React.useState(defaultValue); const [selecting, setSelecting] = React.useState<"hour" | "minute">("hour"); const current = value ? parseTime(value) ?? uncontrolled : uncontrolled; React.useEffect(() => { if (value && parseTime(value)) setText(value); }, [value]); const commit = (next: TimeValue) => { if (value === undefined) setUncontrolled(next); const formatted = formatTime(next); setText(formatted); onValueChange?.(formatted); }; const hour12 = current.hour % 12 || 12; const isPm = current.hour >= 12; const dial = selecting === "hour" ? Array.from({ length: 12 }, (_, index) => index + 1) : [0, 5, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55]; return ( <div data-slot="time-picker" className={cn("flex w-fit flex-col gap-1", className)}> <label className="flex flex-col gap-0.5"> <span>{label}</span> <input value={text} inputMode="numeric" className="w-12 rounded-sm border border-gray-7 bg-gray-1 px-1 py-0.5 text-gray-12 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent-8" onChange={(event) => { const next = event.target.value; setText(next); const parsed = parseTime(next); if (parsed) commit(parsed); }} /> </label> <div className="flex gap-0.5"> <button type="button" aria-pressed={selecting === "hour"} className="rounded-sm px-1 py-0.5 aria-pressed:bg-accent-3 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent-8" onClick={() => setSelecting("hour")} > Hour </button> <button type="button" aria-pressed={selecting === "minute"} className="rounded-sm px-1 py-0.5 aria-pressed:bg-accent-3 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent-8" onClick={() => setSelecting("minute")} > Minute </button> <button type="button" className="rounded-sm px-1 py-0.5 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent-8" onClick={() => commit({ hour: (current.hour + 12) % 24, minute: current.minute })} > {isPm ? "PM" : "AM"} </button> </div> <div role="group" aria-label={selecting === "hour" ? "Hour dial" : "Minute dial"} className="relative size-16 rounded-full border border-gray-6 bg-gray-2" onKeyDown={(event) => { if (event.key !== "ArrowUp" && event.key !== "ArrowDown") return; event.preventDefault(); const delta = event.key === "ArrowUp" ? 1 : -1; if (selecting === "hour") { commit({ hour: (current.hour + delta + 24) % 24, minute: current.minute }); } else { commit({ hour: current.hour, minute: (current.minute + delta + 60) % 60 }); } }} > {dial.map((mark, index) => { const angle = (index / 12) * Math.PI * 2 - Math.PI / 2; const selected = selecting === "hour" ? mark === hour12 : mark === current.minute; return ( <button key={mark} type="button" aria-label={selecting === "hour" ? `${mark}` : `${pad(mark)} minutes`} aria-pressed={selected} className="absolute inline-flex size-3 -translate-x-1/2 -translate-y-1/2 items-center justify-center rounded-full hover:bg-gray-4 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent-8 aria-pressed:bg-accent-9 aria-pressed:text-accent-contrast" style={{ left: `${50 + Math.cos(angle) * 38}%`, top: `${50 + Math.sin(angle) * 38}%`, }} onClick={() => { if (selecting === "hour") { const nextHour = isPm ? (mark % 12) + 12 : mark % 12; commit({ hour: nextHour, minute: current.minute }); setSelecting("minute"); } else { commit({ hour: current.hour, minute: mark }); } }} > {selecting === "hour" ? mark : pad(mark)} </button> ); })} </div> </div> ); } export { TimePicker }; ``` </Step> </Steps> # Timeline (/docs/components/timeline) ## Preview [#preview] <ComponentPreview name="timeline-demo" description="A vertical list of titled moments."> ```tsx import { Timeline, TimelineItem } from "@/components/ui/Timeline"; export function TimelineDemo() { return ( <Timeline> <TimelineItem title="Seed" time="09:00"> Pick a single color. </TimelineItem> <TimelineItem title="Scale" time="09:10"> Build the twelve steps. </TimelineItem> <TimelineItem title="Ship" time="09:30"> Components read the same tokens. </TimelineItem> </Timeline> ) } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/timeline ``` ### Manual [#manual] <Steps> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the Timeline component into your `components/ui/Timeline.tsx` file. ```tsx "use client"; import * as React from "react"; import { cn } from "@/utils/class-names"; function Timeline({ className, label = "Timeline", ...props }: React.ComponentProps<"ol"> & { label?: string }) { return ( <ol aria-label={label} data-slot="timeline" className={cn("flex flex-col gap-1", className)} {...props} /> ); } function TimelineItem({ className, title, time, children, }: { className?: string; title: string; time?: string; children?: React.ReactNode; }) { return ( <li data-slot="timeline-item" className={cn("flex gap-1", className)}> <span aria-hidden className="mt-0.5 size-1 shrink-0 rounded-full bg-accent-9" /> <div className="flex flex-col gap-0.5"> <div className="flex items-baseline gap-0.5"> <span className="font-medium">{title}</span> {time ? <time className="text-gray-11">{time}</time> : null} </div> {children ? <p className="m-0 text-gray-11">{children}</p> : null} </div> </li> ); } export { Timeline, TimelineItem }; ``` </Step> </Steps> # Toast (/docs/components/toast) Aura does not include a Toast component. Apps that need toasts use [sileo](https://github.com/hiaaryan/sileo). Mount `<Toaster />` once, then call `sileo`. ## Preview [#preview] The preview paints the success and error surfaces with the same fill and text tokens as the sileo options below. Dismiss removes a surface. Show toasts brings them back. <ComponentPreview name="toast-demo" description="Success and error toasts with dismiss."> ```tsx "use client"; import { useState } from "react"; import { Button } from "@/components/ui/Button"; const initial = [ { id: "saved", tone: "Success", title: "Saved", description: "The care plan is up to date." }, { id: "error", tone: "Error", title: "Could not save", description: "Check the connection and try again." }, ]; export function ToastDemo() { const [items, setItems] = useState(initial); return ( <div className="grid w-full max-w-xl gap-1"> {items.map((item) => ( <div key={item.id} role="status" className="flex items-start justify-between gap-1 rounded-sm border border-gray-6 bg-gray-1 p-1"> <div> <p className="m-0 text-sm text-gray-11">{item.tone}</p> <p className="m-0 text-gray-12">{item.title}</p> <p className="m-0 text-gray-11">{item.description}</p> </div> <Button type="button" variant="pill" size="sm" onClick={() => setItems((current) => current.filter((entry) => entry.id !== item.id))}> Dismiss </Button> </div> ))} </div> ); } ``` </ComponentPreview> ## Install [#install] ```bash pnpm add sileo ``` ## Mount [#mount] Put the toaster at the root of the app. `offset` is 13 so the toast sits on Aura’s spacing grid. `theme="system"` follows light and dark. `fill` is the toast surface. `styles` values are class names. ```tsx import { sileo, Toaster } from "sileo"; export function AppToaster() { return ( <Toaster position="top-right" theme="system" offset={13} options={{ fill: "var(--gray-1)", styles: { title: "text-gray-12", description: "text-gray-11", }, }} /> ); } ``` ## Call [#call] ```tsx sileo.success({ title: "Saved", description: "The care plan is up to date.", }); sileo.error({ title: "Could not save", description: "Check the connection and try again.", }); const id = sileo.info({ title: "Working", description: "This stays until you dismiss it.", duration: null }); sileo.dismiss(id); ``` `sileo` also exposes `warning`, `action`, `promise`, and `clear`. States are `success`, `loading`, `error`, `warning`, `info`, and `action`. ## Data grid [#data-grid] `DataGrid` still imports `toast` from `sonner` in `DataGridCellVariants.tsx`, `DataGridContextMenu.tsx`, and `use-data-grid.ts`. That call is unchanged here. The follow-up is to point those three call sites at `sileo` so the grid and the rest of the app share one toaster. # Toggle Group (/docs/components/toggle-group) ## Preview [#preview] <ComponentPreview name="toggle-group-demo" description="A group of toggle buttons where one or more options can be selected, with single or multiple selection modes."> ```tsx import { ToggleGroup, ToggleGroupItem } from "@/components/ui/ToggleGroup"; import { TextAlignLeftIcon, TextAlignCenterIcon, TextAlignRightIcon, } from "@radix-ui/react-icons"; export function ToggleGroupDemo() { return ( <ToggleGroup type="single" defaultValue="center" aria-label="Text alignment" > <ToggleGroupItem value="left" aria-label="Left aligned" > <TextAlignLeftIcon /> </ToggleGroupItem> <ToggleGroupItem value="center" aria-label="Center aligned" > <TextAlignCenterIcon /> </ToggleGroupItem> <ToggleGroupItem value="right" aria-label="Right aligned" > <TextAlignRightIcon /> </ToggleGroupItem> </ToggleGroup> ) } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/toggle-group ``` ### Manual [#manual] <Steps> <Step> Install the following dependencies: ```bash pnpm install class-variance-authority radix-ui ``` </Step> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the ToggleGroup component into your `components/ui/ToggleGroup.tsx` file. ```tsx "use client"; import * as React from "react"; import { ToggleGroup as ToggleGroupPrimitive } from "radix-ui"; import { cva, type VariantProps } from "class-variance-authority"; import { cn } from "@/utils/class-names"; const toggleGroupVariants = cva( "inline-flex items-center justify-center border border-gray-6 rounded-sm bg-gray-2", { variants: { variant: { default: "", }, }, defaultVariants: { variant: "default", }, } ); const toggleGroupItemVariants = cva( "inline-flex items-center justify-center gap-2 data-[state=on]:bg-gray-4 data-[state=on]:hover:bg-gray-3", { variants: { variant: { default: "button-pill border border-transparent text-gray-11 bg-gray-2 hover:bg-gray-3 rounded-sm", }, size: { default: "w-3 h-3 p-0", xs: "h-2.5", sm: "h-3", md: "h-4", lg: "h-5", xl: "h-6", icon: "w-3 h-3 p-0", }, }, defaultVariants: { variant: "default", size: "default", }, } ); function ToggleGroup({ className, variant, ...props }: React.ComponentProps<typeof ToggleGroupPrimitive.Root> & VariantProps<typeof toggleGroupVariants>) { return ( <ToggleGroupPrimitive.Root data-slot="toggle-group" className={cn(toggleGroupVariants({ variant, className }))} {...props} /> ); } function ToggleGroupItem({ className, variant, size, ...props }: React.ComponentProps<typeof ToggleGroupPrimitive.Item> & VariantProps<typeof toggleGroupItemVariants>) { return ( <ToggleGroupPrimitive.Item data-slot="toggle-group-item" className={cn(toggleGroupItemVariants({ variant, size, className }))} {...props} /> ); } export { ToggleGroup, ToggleGroupItem, toggleGroupVariants, toggleGroupItemVariants }; ``` </Step> </Steps> # Toggle (/docs/components/toggle) ## Preview [#preview] <ComponentPreview name="toggle-demo" description="A toggle component that allows the user to toggle between on and off states."> ```tsx import { Toggle } from "@/components/ui/Toggle"; import { FontItalicIcon, HeartIcon, HeartFilledIcon, } from "@radix-ui/react-icons"; export function ToggleDemo() { return ( <div className="flex items-center gap-2"> <Toggle> <FontItalicIcon /> </Toggle> </div> ); } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/toggle ``` ### Manual [#manual] <Steps> <Step> Install the following dependencies: ```bash pnpm install class-variance-authority radix-ui ``` </Step> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the Toggle component into your `components/ui/Toggle.tsx` file. ```tsx "use client"; import * as React from "react"; import { Toggle as TogglePrimitive } from "radix-ui"; import { cva, type VariantProps } from "class-variance-authority"; import { cn } from "@/utils/class-names"; const toggleVariants = cva( "inline-flex items-center justify-center gap-2 data-[state=on]:bg-gray-4 data-[state=on]:hover:bg-gray-3", { variants: { variant: { default: "button-pill border border-gray-6 text-gray-11 bg-gray-2 hover:bg-gray-3", }, size: { default: "w-3 h-3 p-0", xs: "h-2.5", sm: "h-3", md: "h-4", lg: "h-5", xl: "h-6", icon: "w-3 h-3 p-0", }, }, defaultVariants: { variant: "default", size: "default", }, } ); function Toggle({ className, variant, size, ...props }: React.ComponentProps<typeof TogglePrimitive.Root> & VariantProps<typeof toggleVariants>) { return ( <TogglePrimitive.Root data-slot="toggle" className={cn(toggleVariants({ variant, size, className }))} {...props} /> ); } export { Toggle, toggleVariants }; ``` </Step> </Steps> ## Usage [#usage] ### ToggleIcons [#toggleicons] ```tsx export const ToggleIcons = () => { return ( <Toggle className="group"> <HeartIcon className="block group-data-[state=on]:hidden icon" /> <HeartFilledIcon className="hidden group-data-[state=on]:block text-accent-9 icon" /> </Toggle> ); }; ``` # Toolbar (/docs/components/toolbar) ## Preview [#preview] <ComponentPreview name="toolbar-demo" description="An always-visible bar of related actions."> ```tsx import { FontBoldIcon, FontItalicIcon, UnderlineIcon } from "@radix-ui/react-icons"; import { Toolbar, ToolbarButton, ToolbarSeparator } from "@/components/ui/Toolbar"; export function ToolbarDemo() { return ( <Toolbar label="Formatting"> <ToolbarButton aria-label="Bold"> <FontBoldIcon className="icon" /> </ToolbarButton> <ToolbarButton aria-label="Italic"> <FontItalicIcon className="icon" /> </ToolbarButton> <ToolbarSeparator /> <ToolbarButton aria-label="Underline"> <UnderlineIcon className="icon" /> </ToolbarButton> </Toolbar> ); } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/toolbar ``` ### Manual [#manual] <Steps> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the Toolbar component into your `components/ui/Toolbar.tsx` file. ```tsx "use client"; import * as React from "react"; import { cn } from "@/utils/class-names"; function Toolbar({ className, label = "Toolbar", ...props }: React.ComponentProps<"div"> & { label?: string }) { return ( <div role="toolbar" aria-label={label} data-slot="toolbar" className={cn( "inline-flex items-center gap-0.5 rounded-sm border border-gray-6 bg-gray-1 p-0.5", className, )} {...props} onKeyDown={(event) => { props.onKeyDown?.(event); if (event.defaultPrevented) return; const items = event.currentTarget.querySelectorAll<HTMLElement>( "[data-slot='toolbar-button']:not([disabled])", ); const list = Array.from(items); const index = list.indexOf(document.activeElement as HTMLElement); if (index < 0) return; if (event.key === "ArrowRight") { event.preventDefault(); list[(index + 1) % list.length]?.focus(); } else if (event.key === "ArrowLeft") { event.preventDefault(); list[(index - 1 + list.length) % list.length]?.focus(); } }} /> ); } function ToolbarButton({ className, pressed, ...props }: React.ComponentProps<"button"> & { pressed?: boolean }) { return ( <button type="button" data-slot="toolbar-button" aria-pressed={pressed} className={cn( "inline-flex size-3 items-center justify-center rounded-sm text-gray-12 hover:bg-gray-3 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent-8 aria-pressed:bg-accent-3", className, )} {...props} /> ); } function ToolbarSeparator({ className, ...props }: React.ComponentProps<"div">) { return ( <div role="separator" aria-orientation="vertical" data-slot="toolbar-separator" className={cn("mx-0.5 h-2 w-px bg-gray-6", className)} {...props} /> ); } export { Toolbar, ToolbarButton, ToolbarSeparator }; ``` </Step> </Steps> # Tooltip (/docs/components/tooltip) ## Preview [#preview] <ComponentPreview name="tooltip-demo" description="A tooltip component that displays informative text when hovering over an element."> ```tsx import { Tooltip, TooltipTrigger, TooltipContent, } from "@/components/ui/Tooltip"; import { Button } from "@/components/ui/Button"; export function TooltipDemo() { return ( <Tooltip> <TooltipTrigger asChild> <Button variant="pill">Hover me</Button> </TooltipTrigger> <TooltipContent> This is a tooltip </TooltipContent> </Tooltip> ) } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/tooltip ``` ### Manual [#manual] <Steps> <Step> Install the following dependencies: ```bash pnpm install radix-ui ``` </Step> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the Tooltip component into your `components/ui/Tooltip.tsx` file. ```tsx "use client" import * as React from "react" import { Tooltip as TooltipPrimitive } from "radix-ui" import { cn } from "@/utils/class-names" function TooltipProvider({ delayDuration = 0, ...props }: React.ComponentProps<typeof TooltipPrimitive.Provider>) { return ( <TooltipPrimitive.Provider data-slot="tooltip-provider" delayDuration={delayDuration} {...props} /> ) } function Tooltip({ ...props }: React.ComponentProps<typeof TooltipPrimitive.Root>) { return ( <TooltipProvider> <TooltipPrimitive.Root data-slot="tooltip" {...props} /> </TooltipProvider> ) } function TooltipTrigger({ ...props }: React.ComponentProps<typeof TooltipPrimitive.Trigger>) { return <TooltipPrimitive.Trigger data-slot="tooltip-trigger" {...props} /> } function TooltipContent({ className, sideOffset = 0, children, ...props }: React.ComponentProps<typeof TooltipPrimitive.Content>) { return ( <TooltipPrimitive.Portal> <TooltipPrimitive.Content data-slot="tooltip-content" sideOffset={sideOffset} className={cn( "bg-gray-12 text-gray-1 z-50 w-fit origin-(--radix-tooltip-content-transform-origin) rounded-md px-1 py-0.5 text-sm text-balance data-[state=open]:animate-tooltip-show data-[state=closed]:animate-tooltip-hide", className )} {...props} > {children} <TooltipPrimitive.Arrow className="fill-gray-12" /> </TooltipPrimitive.Content> </TooltipPrimitive.Portal> ) } export { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider } ``` </Step> </Steps> # Tour (/docs/components/tour) ## Preview [#preview] <ComponentPreview name="tour-demo" description="A short stepped guide that highlights one target at a time."> ```tsx import { Tour, TourTarget } from "@/components/ui/Tour"; export function TourDemo() { return ( <Tour defaultOpen steps={[ { id: "tour-color", title: "Color", body: "Accent steps carry the brand." }, { id: "tour-type", title: "Type", body: "Headings use the fluid scale." }, ]} > <div className="flex gap-1"> <TourTarget id="tour-color">Color</TourTarget> <TourTarget id="tour-type">Type</TourTarget> </div> </Tour> ) ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/tour ``` ### Manual [#manual] <Steps> <Step> Copy and paste the button component into your `components/ui/Button.tsx` file. ```tsx /** * @description Displays a button or a component that looks like a button. / import as React from "react"; import { Slot } from "@radix-ui/react-slot"; import { cva, type VariantProps } from "class-variance-authority"; import { cn } from "@/utils/class-names"; import { Spinner } from "@/components/ui/Spinner"; const buttonVariants = cva("button", { variants: { variant: { default: "button-fill", fill: "button-fill", pill: "button-pill border border-gray-6 text-gray-11 bg-gray-2 hover:bg-gray-3", link: "button-link", menu: "button-menu", }, size: { default: "h-4", xs: "h-2.5", sm: "h-3", md: "h-4", lg: "h-5", xl: "h-6", icon: "w-3 h-3 p-0", "icon-md": "w-4 h-4 p-0", }, }, defaultVariants: { variant: "default", size: "default", }, }); interface ButtonProps extends React.ComponentProps<"button">, VariantProps<typeof buttonVariants> { asChild?: boolean; isDisabled?: boolean; isLoading?: boolean; isLoadingText?: string | React.ReactNode; mode?: VariantProps<typeof buttonVariants>["variant"]; label?: string | React.ReactNode; } const Button = React.forwardRef<HTMLButtonElement, ButtonProps>( (props: ButtonProps, ref) => { const { className, variant, mode, size, asChild = false, isDisabled, isLoading, isLoadingText, children, label, ...rest } = props; const Comp = asChild ? Slot : "button"; const disabled = isDisabled || isLoading || props.disabled; const effectiveVariant = variant ?? mode; return ( <Comp data-slot="button" className={cn( buttonVariants({ variant: effectiveVariant, size, className }), disabled && "opacity-50 cursor-not-allowed" )} ref={ref} disabled={disabled} {...rest} > {asChild ? ( children ) : ( <> {isLoading && isLoadingText ? ( isLoadingText ) : ( <> {isLoading ? <Spinner /> : null} {label} {children} </> )} </> )} </Comp> ); } ); Button.displayName = "Button"; export { Button, buttonVariants }; export type { ButtonProps }; export default Button; ``` </Step> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the Tour component into your `components/ui/Tour.tsx` file. ```tsx "use client"; import * as React from "react"; import { cn } from "@/utils/class-names"; import { Button } from "@/components/ui/Button"; type TourStep = { id: string; title: string; body: string; }; type TourContextValue = { activeId?: string; }; const TourContext = React.createContext<TourContextValue>({}); function Tour({ className, steps, defaultOpen = false, children, label = "Tour", }: { className?: string; steps: TourStep[]; defaultOpen?: boolean; children?: React.ReactNode; label?: string; }) { const [open, setOpen] = React.useState(defaultOpen); const [index, setIndex] = React.useState(0); const dialogRef = React.useRef<HTMLDivElement>(null); const titleId = React.useId(); const step = steps[index]; React.useEffect(() => { if (!open) return; dialogRef.current?.focus(); const onKey = (event: KeyboardEvent) => { if (event.key === "Escape") setOpen(false); if (event.key === "ArrowRight") setIndex((current) => Math.min(steps.length - 1, current + 1)); if (event.key === "ArrowLeft") setIndex((current) => Math.max(0, current - 1)); }; window.addEventListener("keydown", onKey); return () => window.removeEventListener("keydown", onKey); }, [open, steps.length, index]); return ( <TourContext.Provider value={{ activeId: open ? step?.id : undefined }}> <div data-slot="tour" className={cn("flex flex-col gap-1", className)}> {children} {open && step ? ( <div ref={dialogRef} role="dialog" aria-modal="false" aria-label={label} aria-labelledby={titleId} tabIndex={-1} className="flex flex-col gap-0.5 rounded-sm border border-gray-6 bg-gray-1 p-1 shadow-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent-8" > <p id={titleId} className="m-0 font-medium"> {step.title} </p> <p className="m-0 text-gray-11">{step.body}</p> <div className="flex items-center gap-0.5"> <Button type="button" variant="pill" size="sm" disabled={index === 0} onClick={() => setIndex((current) => Math.max(0, current - 1))} > Back </Button> {index < steps.length - 1 ? ( <Button type="button" size="sm" onClick={() => setIndex((current) => Math.min(steps.length - 1, current + 1))} > Next </Button> ) : ( <Button type="button" size="sm" onClick={() => setOpen(false)}> Done </Button> )} <span className="text-gray-11"> {index + 1} / {steps.length} </span> </div> </div> ) : ( <Button type="button" variant="pill" size="sm" className="w-fit" onClick={() => { setIndex(0); setOpen(true); }} > Start tour </Button> )} </div> </TourContext.Provider> ); } function TourTarget({ id, className, children, }: { id: string; className?: string; children?: React.ReactNode; }) { const { activeId } = React.useContext(TourContext); const active = activeId === id; return ( <div id={id} data-slot="tour-target" className={cn( "rounded-sm border border-gray-6 p-1", active && "ring-2 ring-accent-8", className, )} > {children} </div> ); } export { Tour, TourTarget }; export type { TourStep }; ``` </Step> </Steps> # Typography (/docs/components/typography) Aura sets type in CSS. Headings and paragraphs use `clamp()` from custom properties on the element. A Typography component would only repeat those classes, so this page is the specimen. The full rules, the 17px form floor, and the font stacks are on [Typography](/docs/foundations/typography). ## Scale [#scale] | Class | Also on | Role | | -------- | ------------------ | ------------- | | `.h1` | `h1` | Display | | `.h2` | `h2` | Page title | | `.h3` | `h3` | Section | | `.h4` | `h4`, `blockquote` | Subsection | | `.h5` | `h5` | Minor heading | | `.h6` | `h6` | Label heading | | `.p` | `p` | Body | | `.small` | | Small label | | `.xs` | | Micro label | `text-sm` and `text-xs` are the only Tailwind sizes for small UI text. They stay off `input`, `textarea`, and `select`. `.small` is the small-label class: 14px, weight 500, line-height `1.4rem` (23.8px at a 17px root). `.xs` is the micro style: 12px, semibold, line-height 16px (`calc(12 / 17 * 1rem)` and `calc(16 / 17 * 1rem)` at a 17px root). Badges use `.xs`. ## Specimen [#specimen] <h1> Heading one </h1> <h2> Heading two </h2> <h3> Heading three </h3> <h4> Heading four </h4> <h5> Heading five </h5> <h6> Heading six </h6> <p> Body copy uses the paragraph clamp. The root font size is 17px, so 1rem already meets the mobile floor. </p> <p className="h4"> A non-heading can take <code>.h4</code> when the outline should stay flat and the size should match a fourth-level heading. </p> <blockquote> Editorial emphasis uses the same fluid size as h4. </blockquote> <p className="text-sm"> Small utility text uses text-sm. </p> <p className="text-xs"> Micro labels use text-xs. </p> <p className="small"> Small labels use the small class. </p> <p className="xs"> Micro labels use the xs class. </p> # Form Components (/docs/forms/form-components) # Form Components [#form-components] The form UI is built on Radix UI Form primitives. These components consume `field` props from [useFormDynamic](/docs/forms/use-dynamic-form) and, when used inside `Form`, receive `errors` automatically so validation messages show on the right fields. ## Form [#form] The root wrapper. It forwards all props to Radix Form and adds error distribution. Props: Extends Radix `Form.Root` (e.g. `onSubmit`, `id`, `className`, `ref`). In addition: | Prop | Type | Description | | -------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `errors` | `ErrorObject<string, Record<string, any>, unknown>[]` (from AJV) | Validation errors. Form matches each error to a child by `error.instancePath.slice(1) === child.props.field?.name` and injects that slice of errors into the child. | Behavior: Form walks its children (recursively). For any descendant that has a `field` prop, it filters `errors` to those whose `instancePath` (after removing the leading `/`) equals `field.name`, then clones that descendant with an `errors` prop. So you don’t pass `errors` to each field component yourself — Form does it. ```tsx <Form ref={formRef} onSubmit={handleSubmit} errors={formErrors} id="my-form" className="flex flex-col gap-1" > {/* FormField and other components receive errors automatically /} </Form> ``` ## FormSubmit [#formsubmit] Submit button wired to the form, with optional loading state. | Prop | Type | Description | | ------------- | --------------------------------------------- | ---------------------------------------------------------------------- | | `buttonProps` | `ButtonProps` | Props passed to the underlying Button (e.g. `children`, `className`). | | `fetchStatus` | `"idle" \| "loading" \| "success" \| "error"` | When `"loading"`, the button shows a loading indicator (e.g. spinner). | | `form` | `string` | Must match the `id` of the form (for native `form` attribute). | | (others) | Radix `Form.Submit` props | e.g. `disabled`. | ```tsx <FormSubmit fetchStatus={formData.fetchStatus} buttonProps={{ children: "Submit" }} form="my-form" /> ``` ## FormAlert [#formalert] Shows a form-level error when submit fails or validation fails and you set a message. | Prop | Type | Description | | ---------- | ------------------------------------------------ | ------------------------------------------------------------------------ | | `formData` | `{ fetchStatus: string; error: string \| null }` | Renders only when `fetchStatus === "error"` and `formData.error` is set. | Use it with the hook’s `fetchStatus` and `error`: ```tsx <FormAlert formData={{ fetchStatus: formData.fetchStatus, error: formData.error, }} /> ``` ## FormField [#formfield] Generic wrapper for a single native control (input, textarea, or select). Renders a label, the control, and per-field validation messages. | Prop | Type | Description | | -------------- | ------------------------ | --------------------------------------------------------------------------- | | `field` | `FieldProps` | From `formData.getFields()` or `formData.field(name)`. | | `label` | `React.ReactNode` | Label text or node. | | `labelProps` | Radix Form.Label props | Optional. | | `controlProps` | Radix Form.Control props | Optional. | | `errors` | `ErrorObject[]` | Usually injected by Form; only set manually if the field is not under Form. | The control receives `field.onChange` from Form.Control. Use for `<Input>`, `<textarea>`, or native `<select>`. ```tsx <FormField field={name} label="Name "> <Input type="text" placeholder="Your name" /> </FormField> <FormField field={message} label="Message"> <textarea rows={4} /> </FormField> ``` Errors are shown when `field.touch && errors?.length > 0`; each error’s `message` is rendered in a `FormRadix.Message`. ## FormSwitch [#formswitch] Toggle (switch) field. Uses `field.value` (boolean) and `field.onCheckedChange`. | Prop | Type | Description | | -------- | ----------------- | --------------------------------- | | `field` | `FieldProps` | From hook. | | `label` | `React.ReactNode` | Label. | | `errors` | `ErrorObject[]` | Usually from Form. | | `id` | `string` | Optional; default from `useId()`. | ```tsx <FormSwitch field={notifications} label="Enable notifications" /> ``` ## FormCheckbox [#formcheckbox] Single checkbox field. Uses `field.value` (boolean) and `field.onCheckedChange`. | Prop | Type | Description | | -------- | ----------------- | ------------------ | | `field` | `FieldProps` | From hook. | | `label` | `React.ReactNode` | Label. | | `errors` | `ErrorObject[]` | Usually from Form. | | `id` | `string` | Optional. | ```tsx <FormCheckbox field={terms} label="I agree to the terms " /> ``` ## FormCheckboxGroup [#formcheckboxgroup] Group of checkboxes with a shared `field`; value is an array of selected option values. | Prop | Type | Description | | --------- | ----------------------- | ----------------------------------------------------- | | `field` | `FieldProps` | From hook; value is cast to `string[]` for the group. | | `label` | `React.ReactNode` | Optional. | | `options` | `CheckboxGroupOption[]` | `{ value, label, description?, disabled? }`. | | `errors` | `ErrorObject[]` | Usually from Form. | The component calls `field.setValue(value)` with the new array when the user checks/unchecks. ```tsx <FormCheckboxGroup field={interests} label="Interests" options={[ { value: "a", label: "Option A" }, { value: "b", label: "Option B" }, ]} /> ``` ## FormRadioGroup [#formradiogroup] Radio group with a shared `field`; value is a single string. | Prop | Type | Description | | --------- | -------------------- | -------------------------------------------- | | `field` | `FieldProps` | From hook. | | `label` | `React.ReactNode` | Optional. | | `options` | `RadioGroupOption[]` | `{ value, label, description?, disabled? }`. | | `errors` | `ErrorObject[]` | Usually from Form. | The component calls `field.setValue(value)` when the user selects an option. ```tsx <FormRadioGroup field={country} label="Country" options={[ { value: "us", label: "United States" }, { value: "uk", label: "United Kingdom" }, ]} /> ``` ## Summary [#summary] Form – Pass `errors`; it injects the right slice into children that have a `field` prop. * FormSubmit – Submit button; pass `fetchStatus` for loading UI. * FormAlert – Form-level error when `fetchStatus === "error"` and `error` is set. * FormField – Native inputs; uses `field.onChange`. * FormSwitch / FormCheckbox – Boolean fields; use `field.value` and `field.onCheckedChange`. * FormCheckboxGroup / FormRadioGroup – Multi/single choice; use `field.setValue` with array or string. For installation and full demos, see [Form (component)](/docs/components/form). # Form Field Composition (/docs/forms/form-field-composition) # Form Field Composition [#form-field-composition] These components wrap non-native controls (Select, Combobox, Editor, SignaturePad, Sortable) and connect them to [useFormDynamic](/docs/forms/use-dynamic-form) via the same `field` prop used by [FormField](/docs/forms/form-components). They all accept `field?: FieldProps` and `errors?: ErrorObject[]` (typically injected by `Form`), and they update state with `field.setValue`. ## Overview [#overview] | Component | Purpose | Value type | How it uses `field` | | ------------------------- | -------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------- | | FormFieldSelect | Dropdown select | `string` | Does not pass `field.value` to Select (uncontrolled); `onValueChange` → `field.setValue(newValue)`. | | FormFieldCombobox | Searchable single/multi | `string` or `string[]` | `field.setValue(value)` in handler. | | FormFieldEditor | Rich/text block editor | `string` | `field.value` → editor state; `onChange(editorState)` → `field.setValue(editorState)`. | | FormFieldSignaturePad | Signature capture | `string` (e.g. base64) | `onChange(signature)` → `field.setValue(signature \|\| "")`. | | FormFieldSortableList | Drag-and-drop ordered list | `array` | `field.value` normalized to array; `onValueChange` → `field.setValue`. | ## FormFieldSelect [#formfieldselect] Dropdown select built on the Select UI component. | Prop | Type | Description | | -------------- | ----------------- | ----------------------------------- | | `field` | `FieldProps` | From hook. | | `label` | `React.ReactNode` | Optional. | | `options` | `SelectOption[]` | `{ label: string; value: string }`. | | `placeholder` | `string` | Placeholder when empty. | | `disabled` | `boolean` | Default `false`. | | `defaultValue` | `string` | Optional. | | `value` | `string` | Optional controlled value. | | `errors` | `ErrorObject[]` | Usually from Form. | | `className` | `string` | Optional. | The Select is used without passing `field.value` as its controlled value; it updates the form via `onValueChange` → `field.setValue(newValue)`. ```tsx <FormFieldSelect field={country} label="Country " options={[ { label: "United States", value: "us" }, { label: "United Kingdom", value: "uk" }, ]} placeholder="Select a country" /> ``` ## FormFieldCombobox [#formfieldcombobox] Searchable single- or multi-select (Combobox). | Prop | Type | Description | | ------------- | ------------------ | ------------------------------------------------ | | `field` | `FieldProps` | From hook; multi mode uses array value (cast). | | `label` | `React.ReactNode` | Optional. | | `options` | `ComboboxOption[]` | Options for the combobox. | | `multiple` | `boolean` | Default `false`; when true, value is `string[]`. | | `placeholder` | `string` | Optional. | | `disabled` | `boolean` | Default `false`. | | `errors` | `ErrorObject[]` | Usually from Form. | | `className` | `string` | Optional. | Single: `field.setValue(value: string)`. Multiple: `field.setValue(value: string[])` (typed as `string | boolean` on `FieldProps`, cast in the component). ```tsx <FormFieldCombobox field={country} label="Country " options={comboboxOptions} placeholder="Select a country" /> <FormFieldCombobox field={interests} label="Interests" options={interestsOptions} multiple placeholder="Select one or more" /> ``` ## FormFieldEditor [#formfieldeditor] Rich or block text editor. Value is a string (e.g. HTML or editor-specific JSON). | Prop | Type | Description | | ----------- | ----------------- | ------------------ | | `field` | `FieldProps` | From hook. | | `label` | `React.ReactNode` | Optional. | | `errors` | `ErrorObject[]` | Usually from Form. | | `className` | `string` | Optional. | Uses `field.value` as the editor state and `field.setValue(editorState)` on change. ```tsx <FormFieldEditor field={content} label="Content " /> ``` ## FormFieldSignaturePad [#formfieldsignaturepad] Signature capture; value is a string (e.g. base64 image). | Prop | Type | Description | | -------- | -------------------------------------- | --------------------------------------------------------------------------- | | `field` | `FieldProps` | From hook. | | `label` | `React.ReactNode` | Required. | | `errors` | `ErrorObject[]` | Usually from Form. | | `onSave` | `(signature: Base64URLString) => void` | Optional; called when signature is saved in addition to updating the field. | | (others) | SignaturePad props | e.g. `variant`, `size`, `penColor`, `lineWidth`, `showButtons`. | Calls `field.setValue(signature || "")` when the signature changes. ```tsx <FormFieldSignaturePad field={signature} label="Signature " variant="default" size="md" /> ``` ## FormFieldSortableList [#formfieldsortablelist] Drag-and-drop ordered list. Value is an array (stored via `field.setValue`; `FieldProps.value` is typed as `string | boolean`, so the component casts to array). | Prop | Type | Description | | ------------------ | --------------------------------------- | ----------------------------------------------------------- | | `field` | `FieldProps` | From hook; value treated as array. | | `label` | `React.ReactNode` | Optional. | | `errors` | `ErrorObject[]` | Usually from Form. | | `renderItem` | `(item: T, index: number) => ReactNode` | Render each item. Default shows `String(item)`. | | `getItemValue` | `(item: T) => UniqueIdentifier` | Required when items are objects; used for keys and drag id. | | `orientation` | `"vertical" \| "horizontal" \| "mixed"` | Default `"vertical"`. | | `showOverlay` | `boolean` | Default `true`. | | `showHandle` | `boolean` | Default `true`. | | `itemClassName` | `string` | Optional. | | `contentClassName` | `string` | Optional. | Initial value should be an array. You can set it once in an effect if the hook type is `"text"`: ```tsx React.useEffect(() => { if (!Array.isArray(priorities.value)) { priorities.setValue(["High", "Medium", "Low"] as any); } }, []); ``` ```tsx <FormFieldSortableList field={priorities} label="Priorities " renderItem={(item) => <span className="text-gray-12 flex-1">{String(item)}</span>} /> ``` ## Composition pattern [#composition-pattern] Each of these components: 1. Reads `field.name` – Used for `FormRadix.Field` name and for error matching when Form injects `errors`. 2. Uses `field.touch` and `errors` – Sets `serverInvalid` and renders `FormRadix.Message` when `field.touch && errors?.length > 0`. 3. Updates state via `field.setValue` – Non-native controls don’t use `field.onChange`; they call `field.setValue(value)` in their own change handlers. For multi-value components (FormFieldCombobox with `multiple`, FormFieldSortableList), the hook’s `FieldProps.value` is typed as `string | boolean`, but the component treats or casts it to the correct type (e.g. `string[]` or `any[]`). ## Example: mixed composed fields [#example-mixed-composed-fields] ```tsx const formRef = useRef<HTMLFormElement>(null); const formData = useFormDynamic({ country: "text", signature: "text", }); const { country, signature } = formData.getFields(); const { isValid, errors } = validateFormData(schema, formData.getValues()); return ( <Form ref={formRef} onSubmit={handleSubmit} errors={errors ?? undefined} id="demo"> <FormAlert formData={{ fetchStatus: formData.fetchStatus, error: formData.error }} /> <FormFieldSelect field={country} label="Country " options={countryOptions} placeholder="Select country" /> <FormFieldSignaturePad field={signature} label="Signature " variant="default" size="md" /> <FormSubmit fetchStatus={formData.fetchStatus} buttonProps={{ children: "Submit" }} form="demo" /> </Form> ); ``` # Forms Overview (/docs/forms) # Overview [#overview] The Aura Form system gives you a declarative way to handle forms: define field types once, get bound state and handlers, and let the Form component wire validation errors to the right fields. Built on Radix UI Form primitives and designed to work with JSON Schema validation (e.g. [AJV](https://ajv.js.org/)). ## Motivation [#motivation] Most form libraries either lock you into a specific validation or UI pattern, or leave you wiring state and errors by hand. Aura Forms aims for: Declarative structure – Define your form with field names and types; the hook provides values, touch state, and field props. * Shared state – One place for values, errors, touch, and submit status so validation and UI stay in sync. * Automatic error distribution – Pass an array of validation errors to `Form`; it matches errors to fields by name and injects them into the right components. * Composable fields – Use `FormField` for native inputs, or composed components like `FormFieldSelect`, `FormFieldCombobox`, `FormFieldEditor`, `FormFieldSignaturePad`, and `FormFieldSortableList` that all consume the same `field` prop. ## Architecture [#architecture] The system has three parts that work together: ```mermaid flowchart LR subgraph hook [useFormDynamic] types[Field types] value[value state] touch[touch state] field[field name to FieldProps] getFields[getFields] getValues[getValues] end subgraph form [Form] errors[errors prop] processChildren[processChildren] match[instancePath equals field.name] end subgraph fields [FormField and FormField components] fieldProp[field prop] errorsInjected[errors injected by Form] end hook --> getFields getFields --> fieldProp errors --> processChildren processChildren --> match match --> errorsInjected fieldProp --> fields ``` * `useFormDynamic` – Defines field types, holds values/touch/error/fetchStatus, and exposes `field(name)`, `getFields()`, `getValues()`, `resetForm()`, and `touchForm()`. * `Form` – Receives `errors` (e.g. AJV `ErrorObject[]`), walks its children, and injects `errors` into any descendant that has a `field` prop by matching `error.instancePath.slice(1)` to `field.name`. * Form field components – Accept `field` (from `getFields()` or `field(name)`) and optional `errors` (injected by Form). They use `field.value`, `field.setValue`, and for native inputs `field.onChange` / `field.onCheckedChange`, and show messages when `field.touch && errors?.length > 0`. ## Quick example [#quick-example] Minimal form with validation and submit handling: ```tsx import { useRef } from "react"; import { Form, FormField, FormSubmit, FormAlert, } from "@/components/ui/Form"; import { Input } from "@/components/ui/Input"; import { useFormDynamic } from "@/hooks/use-dynamic-form"; import { validateFormData } from "@/utils/web-validation"; const schema = { type: "object", properties: { name: { type: "string" }, email: { type: "string", format: "email" }, }, required: ["name", "email"], }; export function QuickForm() { const formRef = useRef<HTMLFormElement>(null); const formData = useFormDynamic({ name: "text", email: "text", }); const { name, email } = formData.getFields(); const { isValid, errors } = validateFormData(schema, formData.getValues()); const formErrors = errors ?? undefined; const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => { e.preventDefault(); formData.setFetchStatus("loading"); if (!isValid) { formData.setFetchStatus("error"); formData.touchForm(); formData.setError("Please complete all required fields"); return; } // Simulate or call your API await new Promise((r) => setTimeout(r, 500)); formData.setFetchStatus("success"); }; return ( <Form ref={formRef} onSubmit={handleSubmit} errors={formErrors} id="quick-form" className="flex flex-col gap-1" > <FormAlert formData={{ fetchStatus: formData.fetchStatus, error: formData.error, }} /> <FormField field={name} label="Name "> <Input type="text" placeholder="Your name" /> </FormField> <FormField field={email} label="Email "> <Input type="email" placeholder="your@email.com" /> </FormField> <FormSubmit fetchStatus={formData.fetchStatus} buttonProps={{ children: "Submit" }} form="quick-form" /> </Form> ); } ``` ## Next steps [#next-steps] * [useFormDynamic](/docs/forms/use-dynamic-form) – Hook API, parameters, return value, and `FieldProps`. * [Form components](/docs/forms/form-components) – `Form`, `FormSubmit`, `FormAlert`, `FormField`, `FormSwitch`, `FormCheckbox`, and groups. * [Form field composition](/docs/forms/form-field-composition) – `FormFieldSelect`, `FormFieldCombobox`, `FormFieldEditor`, `FormFieldSignaturePad`, `FormFieldSortableList`. * [Validation](/docs/forms/validation) – `validateFormData`, error shape, touch behavior, and form-level errors. For installation and more demos, see [Form (component)](/docs/components/form). # useFormDynamic (/docs/forms/use-dynamic-form) # useFormDynamic [#useformdynamic] `useFormDynamic` manages form state: field values, touch state, form-level error, and submit status. It also acts as a factory for field props that you pass into Form components (`FormField`, `FormFieldSelect`, etc.). ## Parameters [#parameters] | Parameter | Type | Required | Description | | ---------------- | ------------------------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `initialValues` | `Record<string, FieldType>` | Yes | Object whose keys are field names and values are field types. Used to initialize values and to know which fields exist. | | `formGeneralRef` | `React.RefObject<HTMLFormElement \| null>` | No | Optional ref to the form element. When provided, each field’s `setValue` can sync the value to a DOM input with a matching `name` attribute. | Field types: `"text" | "textarea" | "select" | "checkbox"` Example: ```tsx const formRef = useRef<HTMLFormElement>(null); const formData = useFormDynamic( { name: "text", email: "text", country: "select", acceptTerms: "checkbox", }, formRef ); ``` ## Return value [#return-value] The hook returns the following. ### Form state (from internal field state) [#form-state-from-internal-field-state] | Property | Type | Description | | ---------- | ------------------------------------- | -------------------------------------------- | | `value` | `Record<string, string \| boolean>` | Current values keyed by field name. | | `setValue` | `React.Dispatch<SetStateAction<...>>` | Setter for the whole value object. | | `error` | `string \| null` | Form-level error message (e.g. from submit). | | `setError` | `(error: string \| null) => void` | Set form-level error. | | `touch` | `Record<string, boolean>` | Touch state per field. | | `setTouch` | `React.Dispatch<SetStateAction<...>>` | Setter for touch state. | | `types` | `Record<string, FieldType>` | Field types (same as `initialValues`). | ### Field factory and bulk getters [#field-factory-and-bulk-getters] | Property | Type | Description | | ------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | `field(name)` | `(name: string) => FieldProps` | Returns the props for a single field. Use with any Form field component. | | `getFields()` | `() => Record<string, FieldProps>` | Returns an object of all field names to their `FieldProps`. Typical: `const { name, email } = formData.getFields()`. | | `getValues()` | `() => Record<string, string \| boolean>` | Returns current values keyed by field name. Use for validation or submit. | ### Form actions [#form-actions] | Property | Type | Description | | ------------------------------------ | --------------------------------------------- | ----------------------------------------------------------------------------------------------- | | `resetForm(formRef, initialValues?)` | `(formRef, initialValues?) => void` | Resets all fields to defaults (or optional `initialValues`) and syncs DOM when ref is provided. | | `touchForm()` | `() => void` | Marks every field as touched. Call after failed validation so all errors show. | | `fetchStatus` | `"idle" \| "loading" \| "success" \| "error"` | Submit/fetch status. | | `setFetchStatus(status)` | `(status) => void` | Set submit status; `FormSubmit` uses `fetchStatus === "loading"` for loading UI. | ## FieldProps [#fieldprops] `field(name)` and `getFields()` return objects that implement this shape. Pass them as the `field` prop to Form components. | Property | Type | Description | | ----------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------- | | `name` | `string` | Field name (matches key in `initialValues`). | | `type` | `FieldType` | `"text" \| "textarea" \| "select" \| "checkbox"`. | | `value` | `string \| boolean` | Current value. Use for controlled inputs or for display. | | `setValue(value)` | `(value: string \| boolean) => void` | Updates state and, when `formGeneralRef` is set, syncs to DOM `[name="..."]` if present. | | `onChange` | `(event: ChangeEvent<...>) => void` | For native inputs (input, textarea, select). Use on the control. | | `onCheckedChange` | `(checked: boolean) => void` (and change handler type) | For checkboxes and switches. | | `touch` | `boolean` | Whether this field has been touched. | | `setTouch` | `(value: boolean) => void` | Set touch state for this field. | | `reset` | `() => void` | Resets this field to its type default and clears touch. | Note: Composed components (e.g. `FormFieldSelect`, `FormFieldCombobox`, `FormFieldEditor`) don’t use native inputs; they call `field.setValue(value)` when the user changes the value. The hook’s `FieldProps.value` is typed as `string | boolean`, but some of these components use arrays (e.g. multi select, sortable list) and cast as needed. ## Initial value resolution [#initial-value-resolution] Values are initialized from the field type: | Field type | Initial value | | ---------- | ------------- | | `text` | `""` | | `textarea` | `""` | | `select` | `""` | | `checkbox` | `false` | ## setValue and DOM sync [#setvalue-and-dom-sync] When you pass `formGeneralRef` to `useFormDynamic`, each field’s `setValue` does two things: 1. Updates the hook’s state (so `getValues()` and `field.value` reflect the new value). 2. If the form ref is set and there is an element with `[name="<fieldName>"]` (input, textarea, or select), it updates that element’s value or checked state so the DOM stays in sync. If you don’t pass `formGeneralRef`, or the form doesn’t contain a matching native control, `setValue` only updates state. That’s the normal case when using composed components (Select, Combobox, Editor, etc.), which are controlled via `field.value` and `field.setValue` and don’t rely on a hidden native input with the same name. # Validation (/docs/forms/validation) # Validation [#validation] The form system is designed to work with JSON Schema validation. Validate with `validateFormData(schema, formData.getValues())`, pass the returned errors to `Form`, and the Form component distributes them to the correct fields. Field errors only show when the field has been touched; on submit you can call `touchForm()` so all errors appear after a failed validation. ## Flow [#flow] 1. Validate – Call `validateFormData(schema, formData.getValues())` (e.g. from `@/utils/web-validation` or your own AJV setup). You get `{ isValid, errors }`. 2. Pass errors to Form – Use `errors` (or `errors ?? undefined`) as the `errors` prop on `<Form>`. 3. Match by field name – Form walks its children and, for any descendant with a `field` prop, filters `errors` to those whose `instancePath` (with the leading `/` removed) equals `field.name`, then injects that slice as the `errors` prop. 4. Show messages – Each form field component shows validation messages when `field.touch && errors?.length > 0`. So: schema property names must match the field names you use in `useFormDynamic` and when calling `getFields()`. For example, if your schema has `required: ["email"]` and a property `email`, the field must be defined as `email: "text"` and used as `field={email}` so that the error with `instancePath: "/email"` is attached to that field. ## validateFormData [#validateformdata] If you use the provided utility (from `@/utils/web-validation`): ```ts import { validateFormData } from "@/utils/web-validation"; ``` Signature: `validateFormData(schema: object, data: unknown) => { isValid: boolean; errors: ErrorObject[] | null }` * schema – JSON Schema object (e.g. `type: "object"`, `properties`, `required`). The utility uses AJV with `allErrors: true`, `$data: true`, and `ajv-formats` / `ajv-errors`. * data – Usually `formData.getValues()`. Return: * When valid: `{ isValid: true, errors: null }`. * When invalid: `{ isValid: false, errors: ErrorObject[] }`. Pass `errors` (or `errors ?? undefined`) to `<Form errors={formErrors}>`. ## AJV error shape [#ajv-error-shape] Errors are AJV [ErrorObject](https://ajv.js.org/docs/api.html#error-objects). The Form component cares about: | Property | Description | | -------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `instancePath` | JSON Pointer to the invalid data, e.g. `"/email"` or `"/name"`. Form matches the field by `error.instancePath.slice(1) === field.name`. | | `message` | Human-readable message; form field components render this in `FormRadix.Message`. | Other properties (e.g. `keyword`, `params`) are available if you need them for custom UI or logging. Important: Use property names in your schema that match your form field names so that `instancePath` lines up. Nested paths (e.g. `"/address/city"`) would require a field name like `"address/city"` or custom error distribution logic. ## Touch and submit [#touch-and-submit] Field-level errors are only shown when the field has been touched (`field.touch` is true). That avoids showing errors for every field as soon as the user focuses the first one. On submit: 1. Run validation with `formData.getValues()`. 2. If validation fails, call `formData.touchForm()` so every field is marked touched; then set `errors` on Form so all relevant messages appear. 3. Optionally set a form-level message with `formData.setError("...")` and show it with `FormAlert`. Example: ```tsx const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => { e.preventDefault(); formData.setFetchStatus("loading"); const { isValid, errors } = validateFormData(schema, formData.getValues()); if (!isValid) { formData.setFetchStatus("error"); formData.touchForm(); formData.setError("Please fix the errors below."); return; } // Submit... formData.setFetchStatus("success"); }; return ( <Form ref={formRef} onSubmit={handleSubmit} errors={errors ?? undefined} id="form-id"> <FormAlert formData={{ fetchStatus: formData.fetchStatus, error: formData.error }} /> {/* fields /} </Form> ); ``` ## Form-level error [#form-level-error] Use the hook’s `error` and `setError` for messages that aren’t tied to a single field (e.g. “Please complete all required fields”, or a server error). Set it when validation fails or when the server returns an error: ```tsx formData.setError("Please complete all required fields."); ``` Render it with FormAlert, passing the current status and error: ```tsx <FormAlert formData={{ fetchStatus: formData.fetchStatus, error: formData.error, }} /> ``` FormAlert only renders when `fetchStatus === "error"` and `formData.error` is set. Clear the message when the user corrects the form or when you reset (e.g. `formData.setError(null)`). # Accessibility (/docs/foundations/accessibility) Products have to be usable by any person who reaches them. That is the first product principle: interfaces are perceivable and operable. The visual system backs that with contrast targets, visible focus, a type floor on editable fields, and motion that can be turned down. ## Best practices [#best-practices] Give every interactive control a visible focus treatment. Strong borders and focus rings use step 8. The shared outline token is `--aura-outline` (`var(--accent-9) solid 2px` in `globals.css`). * Keep steps 11 and 12 as the text pair. The color rule requires those steps to hit APCA Lc 60 and Lc 90 on a step 2 background. * Leave editable `input`, `textarea`, and `select` at 17px or larger. iOS Safari zooms the viewport when a focused field is smaller. * Honor `prefers-reduced-motion`. Overlay and content animations set `animation: none` under that media query. * Prefer native elements and Radix primitives so keyboard behavior, roles, and names come with the control. Interactive components ship with keyboard operation, visible focus, an accessible name, and a correct role. * Keep touch targets padded on the 13px scale. Sidebar and navigation collapse into sheet or drawer patterns on narrow screens. ## Contrast and focus [#contrast-and-focus] | Concern | Aura rule | Where it lives | | --------------------------- | -------------------------------------------------------------------------- | ------------------------------------- | | Secondary text | Step 11 | Color rule, `DESIGN.md` §2 | | Primary text | Step 12 | Color rule, `DESIGN.md` §2 | | Contrast target | Lc 60 (step 11) and Lc 90 (step 12) on step 2 | `.cursor/rules/fundations-colors.mdc` | | Subtle borders | Step 6 | Color rule | | Interactive borders | Step 7 | Color rule | | Focus rings | Step 8, or `--aura-outline` | `DESIGN.md` §6, `globals.css` | | Text on a solid accent fill | `--accent-contrast` / `--primary-foreground` (`#fff` in the shipped theme) | `globals.css` | Controls and dialogs keep legible borders. Marketing layouts may separate sections with background steps and space; inputs, buttons, and focus rings still use steps 6–8. ## Type that stays readable [#type-that-stays-readable] `html { font-size: 17px; }` in the base layer, so `1rem` already meets the mobile floor. An unlayered rule then forces editable text fields: ```css input:not([type="checkbox"]):not([type="radio"]):not([type="range"]):not([type="file"]):not([type="hidden"]):not([type="button"]):not([type="submit"]):not([type="reset"]):not([type="image"]):not([type="color"]), textarea, select { font-size: max(1rem, 17px); } ``` That block lives in `packages/registry/styles/globals.css` and again in `packages/registry/styles/main.css`, outside `@layer`, so it wins over Tailwind `text-sm` / `text-xs`. Checkbox, radio, range, file, and button inputs are exempt. `text-sm` and `text-xs` stay available for non-editable meta text. Body line-height on `html` is 1.21053, inside the 1.1–1.3 range the typography rule asks for on large headings. ## Motion [#motion] Reduced motion is part of accessibility, specified on the [Motion](/docs/foundations/motion) page. Dialog, alert dialog, accordion, collapsible, tooltip, popover, sheet, and sidebar styles each include a `prefers-reduced-motion: reduce` block. ## Related [#related] * [Principles](/docs/rules/principles) * [Color](/docs/foundations/color) * [Typography](/docs/foundations/typography) * [Motion](/docs/foundations/motion) * `DESIGN.md` §1, §2, §3, §8 # Color (/docs/foundations/color) Color in Aura is two 12-step scales — accent and gray — plus alpha twins and a short list of semantic names. Components consume the tokens. Hex samples in this page are the values shipped in `packages/registry/styles/globals.css` and the theme switcher defaults. They are a theme, not a license to hard-code a swatch in a component. `@shadcn/lint` rule `shadcn/no-raw-colors` rejects raw palette classes (`bg-pink-500` and similar) when a token exists. ## Step roles [#step-roles] The same step means the same job in light and dark. Only the hex changes. | Step | Use | | ---- | --------------------------------------- | | 1–2 | App background, cards, sidebars, canvas | | 3 | Default UI fill | | 4 | Hover fill | | 5 | Active or selected fill | | 6 | Subtle borders, separators, headers | | 7 | Interactive borders | | 8 | Strong borders and focus rings | | 9 | Solid brand surfaces | | 10 | Hover on a step-9 surface | | 11 | Secondary text | | 12 | Primary text and headings | On a transparent default, hover may use step 3. `--primary` maps to `--accent-9`. Text on that fill uses `--primary-foreground`, which aliases `--accent-contrast`. Steps 11 and 12 are chosen so APCA Lc 60 and Lc 90 hold on a step 2 background. ## Shipped accent scale [#shipped-accent-scale] Light lives on `:root`. Dark lives in `@media (prefers-color-scheme: dark)` on `:root:not(.light)` and on `.dark`. Step 9 is `#4015ca` in both schemes. See [Theming](/docs/foundations/theming). Light: | Token | Value | | -------------------------------------- | ----------- | | `--accent-1` | `#fdfdff` | | `--accent-2` | `#f7f8ff` | | `--accent-3` | `#eef1ff` | | `--accent-4` | `#e2e7ff` | | `--accent-5` | `#d5dcff` | | `--accent-6` | `#c5cdff` | | `--accent-7` | `#b0b9ff` | | `--accent-8` | `#939bff` | | `--accent-9` | `#4015ca` | | `--accent-10` | `#3500b6` | | `--accent-11` | `#5446e1` | | `--accent-12` | `#272370` | | `--accent-contrast` | `#fff` | | `--accent-surface` | `#f5f6ffcc` | | `--accent-indicator`, `--accent-track` | `#4015ca` | Dark (Somos Gente Digital scale, `#30a` written as `#3300aa`): | Token | Value | | -------------------------------------- | ----------- | | `--accent-1` | `#0b0c22` | | `--accent-2` | `#121331` | | `--accent-3` | `#1e1167` | | `--accent-4` | `#2b0096` | | `--accent-5` | `#3300aa` | | `--accent-6` | `#3b18bb` | | `--accent-7` | `#4626d4` | | `--accent-8` | `#542bfd` | | `--accent-9` | `#4015ca` | | `--accent-10` | `#3400ab` | | `--accent-11` | `#a3acff` | | `--accent-12` | `#d9dfff` | | `--accent-surface` | `#15175280` | | `--accent-indicator`, `--accent-track` | `#4015ca` | Alpha steps `--accent-a1` through `--accent-a12` are defined beside the solid scale in the same file. Tailwind reads them as `accent-1` … `accent-a12` through the `@theme inline` color mappings (`--color-accent-9: var(--accent-9)`, and the same pattern for every step). Semantic aliases in that file: ```css --primary: var(--accent-9); --primary-foreground: var(--accent-contrast); --secundary: var(--accent-8); --secundary-foreground: var(--accent-contrast); ``` The token is spelled `--secundary` in source. `--aura-accents-primary` and `--aura-accents-secondary` both point at `--accent-9`. `--aura-bg` is `--gray-1`. `--aura-text-primary` is `--accent-12` in this theme file. `ThemeColorSwitcher` seeds are accent `#4015ca`, gray `#7254cb`, and backgrounds `#ffffff` / `#100b21`. The switcher generates a scale with `generateRadixColors` and stores it under `aura-theme-colors`. The shipped dark scale in `globals.css` is the Somos Gente Digital ramp, not a fresh generator pass. Production components still read the CSS variables, not those seeds. ## Shipped gray scale [#shipped-gray-scale] Light (`:root`): | Token | Value | | ----------- | --------- | | `--gray-1` | `#fcfaff` | | `--gray-2` | `#f9f6ff` | | `--gray-3` | `#f0ecff` | | `--gray-4` | `#e8e2ff` | | `--gray-5` | `#e0daff` | | `--gray-6` | `#d9d1ff` | | `--gray-7` | `#cfc4ff` | | `--gray-8` | `#bcabff` | | `--gray-9` | `#936cff` | | `--gray-10` | `#8863f2` | | `--gray-11` | `#6949bf` | | `--gray-12` | `#27005f` | Dark (`prefers-color-scheme: dark` and `.dark`): | Token | Value | | ----------- | --------- | | `--gray-1` | `#100b21` | | `--gray-2` | `#19152b` | | `--gray-3` | `#231d3c` | | `--gray-4` | `#2b214d` | | `--gray-5` | `#33265c` | | `--gray-6` | `#3c2d6c` | | `--gray-7` | `#4a3786` | | `--gray-8` | `#6548b6` | | `--gray-9` | `#7254cb` | | `--gray-10` | `#7f63d9` | | `--gray-11` | `#b5a2ff` | | `--gray-12` | `#eeecff` | `--gray-contrast` is `#ffffff` in both schemes. Light `--gray-surface` is `#ffffffcc`. Dark `--gray-surface` is `rgba(0, 0, 0, 0.05)`. `--gray-indicator` and `--gray-track` follow step 9 (`#936cff` light, `#7254cb` dark). Alpha steps sit next to the solid scale. `--ecru` is `#debc7a` and paints `::selection`. Chart series are `--chart-1` through `--chart-5`. Light `--chart-1` is `--accent-9`. Dark `--chart-1` is `--accent-11` so the series clears 3:1 on gray-1. `--chart-2` through `--chart-5` follow the status contrast tokens. Body copy uses the gray scale. `DESIGN.md` tells you to reach for `gray-12` and leave pure `#000` out of text. ## Status pairs [#status-pairs] `@theme inline` in `globals.css`: | Role | Surface | Contrast | | ------- | -------------------- | ----------------------------- | | Info | `--info: #e8ebfe` | `--info-contrast: #0927ec` | | Success | `--success: #e8fef7` | `--success-contrast: #045d3c` | | Danger | `--danger: #feefe8` | `--danger-contrast: #8e3106` | | Warning | `--warning: #fefbe8` | `--warning-contrast: #5d5104` | `.dark` overrides those four pairs (info `#0D2157` / `#8CB4FF`, success `#0B2E1E` / `#67CF9D`, danger `#3C1405` / `#FF9469`, warning `#2A2402` / `#EFE08E`). Stylus still paints status through older names. `packages/styled-system/src/tokens/_root.styl` sets `--aura-accents-success: #045D3C`, `--aura-accents-info: #0927EC`, `--aura-accents-danger: #8E3106`, and a warning darkened from yellow. `fundations/_colors.styl` loops `warning`, `info`, `danger`, and `success` into `.{state}` background classes. The compiled `main.css` still emits `.warning`, `.info`, `.danger`, `.success` against `--aura-accents--bg`. ## Related [#related] [Color rules](/docs/rules/fundations-colors) * [Theming](/docs/foundations/theming) * [Taste](/docs/taste) * [Lint](/docs/lint) * `packages/registry/styles/globals.css` * `packages/registry/registry/default/components/ThemeColorSwitcher.tsx` # Components (/docs/foundations/components) Aura is a registry, distributed in shadcn mode. You copy the source into your app and own it. Items are addressed as `@aura/<name>` once `components.json` points `registries["@aura"]` at the registry. The catalog of installed components lives at [Components](/docs/components). This page is the foundation those components share. ## Best practices [#best-practices] * Change appearance through variants and sizes on the component. `shadcn/no-restyle` rejects padding, color, and typography overrides passed through `className` on a design-system primitive. Layout and width at the call site are fine. * Form controls own their padding. `Input`, `Textarea`, `SelectTrigger`, `MaskInput`, and `SegmentedInput` take layout and width only. A different padding is a new size or variant on the component. * Compose with Radix `asChild`. The child spreads props and forwards a ref. See [Patterns](/docs/foundations/patterns). * Icons inside `Button` and `Badge` get the `icon` class and nothing else for spacing. The control already sets the gap. See [Icons](/docs/foundations/icons). * Keep one paved path. Public APIs grow by additive props and variants. Renames and removals are breaking changes and belong in the PR notes. ## What a component is made of [#what-a-component-is-made-of] Registry source is `packages/registry/registry/default/components/`. Styles that travel with a component live in `packages/registry/registry/default/styles/`. Shared layout, type, and the `icon` class live in `packages/registry/styles/main.css`. Theme tokens live in `packages/registry/styles/globals.css`. `Button` is the reference shape. Variants in `Button.tsx` map onto classes in `main.css`: | Variant | Class | Treatment in `main.css` | | ------------------ | ------------- | -------------------------------------------------------- | | `default` / `fill` | `button-fill` | Solid `--aura-accents-primary`, 2px border, inverse text | | `pill` | `button-pill` | Transparent fill, border and text from `--aura-link` | | `link` | `button-link` | No border, underline | | `menu` | `button-menu` | No border, bold, tighter padding | Shared button metrics from `globals.css` and `main.css`: | Token or property | Value | | ---------------------- | ---------------------------------- | | `--aura-button-radius` | `6.5px` | | `--aura-button-gap` | `6.5px` | | Height | `calc(var(--aura) * 4)` → 52px | | Padding | `0 calc(var(--aura) * 2)` → 0 26px | | Border | `2px solid` | | Label weight | `600` | `Card` defaults to `bg-gray-2`, `border-gray-6`, and `rounded-(--radius-md)` (`--radius-md`, 13px), with a `border-t border-gray-6` footer. `CardTitle` is `.small` semibold. `CardDescription` and body copy use `.small`. `CardAction` is the right-hand slot of `CardHeader`. `Empty` is a centered column, dashed `gray-6` border, `gray-2` fill, `p-2` on the 13px grid. Install with: ```bash pnpm dlx shadcn@latest add @aura/<registry-name> ``` `aura init` wraps that CLI and applies Aura fixtures. Upstream updates are a fresh copy of the source you already own. ## Related [#related] * [Components catalog](/docs/components) * [Patterns](/docs/foundations/patterns) * [Registry](/docs/registry) * [Lint](/docs/lint) * `DESIGN.md` §4 # Data visualization (/docs/foundations/data-visualization) Charts use the same color, type, and motion rules as the rest of Aura. Families live in the [Charts](/docs/charts) section: [area](/docs/charts/area-chart), [bar](/docs/charts/bar-chart), [line](/docs/charts/line-chart), [pie](/docs/charts/pie-chart), [radar](/docs/charts/radar-chart), [radial](/docs/charts/radial-chart), and [tooltips](/docs/charts/chart-tooltips). They are drawn with Recharts and the `@aura/chart` container. ## Series [#series] Five series tokens live on `:root` in `packages/registry/styles/globals.css`. They point at colors that already exist, so a theme change retints the chart. | Token | Points at | Role | | ----------- | -------------------------------------------- | ------------------- | | `--chart-1` | `--accent-9` in light; `--accent-11` in dark | First series, brand | | `--chart-2` | `--info-contrast` | Second series | | `--chart-3` | `--success-contrast` | Third series | | `--chart-4` | `--warning-contrast` | Fourth series | | `--chart-5` | `--danger-contrast` | Fifth series | Under `.dark` and `prefers-color-scheme: dark`, `--chart-1` is `--accent-11` (`#a3acff`). Dark `--accent-9` (`#4015ca`) is 1.99:1 and `--accent-10` (`#3400ab`) is 1.59:1 on `--gray-1` (`#100b21`). Accent-11 is 9.07:1, the first step that clears the 3:1 floor for chart graphics. `--chart-2` through `--chart-5` use the lighter status-contrast values (`#8cb4ff`, `#67cf9d`, `#efe08e`, `#ff9469`). A chart config passes those tokens through. The container writes `--color-<series>` for the plot. A plain CSS color (`#4015ca`, `rgb()`, `hsl()`, or a named color) is kept. Anything else is dropped, and development builds warn. ## Axes, grid, and surface [#axes-grid-and-surface] | Part | Rule | | ----------- | --------------------------------------------------------------------------------------------------------- | | Grid | Gray step 6, solid | | Tick labels | Gray step 11, 13px (`text-xs` is the utility size; ticks are set at 13px) | | Tooltip | `gray-1` surface, gray step 6 border, `rounded-sm`. Values use `font-mono` and `tabular-nums` | | Markers | `--chart-marker` is 8px. The line marker is `--chart-marker-line` (2px). These are not 13px spacing steps | | Plot focus | Accent step 8, 2px outline | | Card | Chart families sit in `Card`: `gray-2` fill, gray step 6 border, `--radius-md` | There is no separate annotation, axis-title, or chart-palette scale beyond these five series. ## Motion [#motion] `ChartArea`, `ChartBar`, `ChartLine`, `ChartPie`, `ChartRadar`, and `ChartRadialBar` animate for 250ms with `ease-out`. `prefers-reduced-motion: reduce` sets `isAnimationActive` to false. The chart stylesheet also shortens CSS animation and transitions on the plot. ## What is still open [#what-is-still-open] `@aura/data-grid` remains a table, with its own type and spacing rules, and is not this chart system. ## Related [#related] * [Charts](/docs/charts) * [Color](/docs/foundations/color) * [Theming](/docs/foundations/theming) * [Motion](/docs/foundations/motion) * `packages/registry/registry/default/components/ui/Chart.tsx` * `packages/registry/registry/default/styles/chart.css` # Depth and elevation (/docs/foundations/elevation) Aura specifies depth in `DESIGN.md` §6, so this page records that system. Surfaces separate by radius, background step, and border step. A numbered elevation or shadow ramp is not defined. ## Radius [#radius] Radius tokens are multiples of `--spacing` (13px), from `@theme inline` in `globals.css`: | Token | Formula | At 13px | | ------------- | ---------------------------- | ------- | | `--radius-sm` | `calc(var(--spacing) * 0.5)` | 6.5px | | `--radius-md` | `calc(var(--spacing) * 1)` | 13px | | `--radius-lg` | `calc(var(--spacing) * 1.5)` | 19.5px | | `--radius-xl` | `calc(var(--spacing) * 2)` | 26px | Component tokens beside those: | Token | Value in `globals.css` | | ---------------------- | ---------------------- | | `--aura-input-radius` | `6.5px` | | `--aura-button-radius` | `6.5px` | | `--aura-radius` | `0.5rem` | Page-level chrome uses at least `rounded-sm` / `--radius-sm`. Outer registry cards can use `rounded-xl`; nested items step down to `rounded-md` when the hierarchy should come from radius rather than another border. ## Tonal sheets [#tonal-sheets] Stack backgrounds before adding lines: | Layer | Step | | -------------- | -------------------- | | Canvas | `gray-1` | | Secondary band | `gray-2` | | Lifted card | `gray-2` or `gray-3` | `main` uses `background-color: var(--gray-1)`. Default `Card` uses `bg-gray-2` and `border-gray-6`. An editorial card may drop the border (`border-0`), take `rounded-xl` and `bg-gray-3`, and let padding carry the edge. Dialogs, menus, inputs, and focus rings keep visible structure. When a surface sits on a similar background, a ghost outline is a low-alpha stroke of `gray-7` or `gray-8` (about 10–15% alpha). That recipe is written in `DESIGN.md` §6. It is not a separate CSS token. ## Shadows [#shadows] Aura does not ship a shadow scale. Components that need a lift use a soft tinted shadow when the design asks for one: blur on the order of 32–64px, opacity on the order of 4–6%, color biased toward the accent. `DESIGN.md` states that range as guidance for custom shadows. There is no `--shadow-1` … `--shadow-n` ramp in `globals.css` or the Stylus tokens. Focus stays on step 8 or `--aura-outline` (`var(--accent-9) solid 2px`), which reads as a ring rather than a drop shadow. `DESIGN.md` also allows a semi-transparent panel (about 70% opacity on `gray-1` or `gray-2`) with `backdrop-blur` around 20px for floating registry panels, provided contrast holds and reduced transparency is respected where the platform exposes it. That treatment is a pattern, not a token. ## Related [#related] * [Layout](/docs/foundations/layout) * [Color](/docs/foundations/color) * [Theming](/docs/foundations/theming) * `DESIGN.md` §6 # Figma (/docs/foundations/figma) Not defined yet. Aura distributes components as source through the registry (`@aura/<name>`), the CLI, and the docs site. There is no Aura Figma library, variable collection, or code-connect mapping in this repository. Designers working from the codebase should read [Foundations](/docs/foundations), `DESIGN.md`, and the [Taste](/docs/taste) page. Those are the specs a Figma library would have to follow if one is added later. # Icons (/docs/foundations/icons) Icons are type. They inherit font size, sit on the text baseline, and take their distance from the label via the parent’s gap. Aura’s default library is `@radix-ui/react-icons`. A project keeps a single icon library. If a second library is already present, the pair is Radix plus that one other set (for example `lucide-react`). New icons still come from the designated library. ## Best practices [#best-practices] * Import from `@radix-ui/react-icons`. * Set `className="icon"`. Leave off `size`, `width`, and `height`. * To scale an icon, add a typography class: `icon` for body size, `icon h4` for a medium mark, `icon h1` for a large one. * Space an icon from a label with `gap` on the flex container. `gap-0.5` is 6.5px. `gap-2` is 26px on this grid. * Inside `Button` and `Badge`, add no margin and no extra gap. The control already owns it (`--aura-button-gap` on `.button` and its variants; `gap-0.5` on `Badge`). * `ml-auto` and `mr-auto` may push a trailing chevron to the end. They are layout, not a substitute for gap. * `aura/no-icon-margin` reports `ml-`, `mr-`, `mx-`, `ms-`, and `me-` on an icon inside a control that already has a gap. ```tsx import { CheckIcon } from "@radix-ui/react-icons"; <CheckIcon className="icon" /> <CheckIcon className="icon h1" /> <Button><CheckIcon className="icon" />Save</Button> <div className="flex items-center gap-0.5"><CheckIcon className="icon" />Saved</div> ``` ## The `icon` class [#the-icon-class] From `packages/registry/styles/main.css` (and `packages/styled-system/src/atoms/_icon.styl`): ```css .icon { width: 1em; height: 1em; display: inline-block; line-height: 1em; flex-shrink: 0; vertical-align: middle; } ``` Because width and height are `1em`, an icon inside `.h4` matches that heading’s computed size. The fluid type scale on `.h1`–`.h6` is what makes `icon h1` large. ## Related [#related] [Icon rules](/docs/rules/fundation-icons) * [Components](/docs/foundations/components) * [Lint](/docs/lint) * `DESIGN.md` §1 and §4 # Foundations (/docs/foundations) Foundations are the rules Aura already encodes: tokens in CSS, Stylus variables in the styled system, component behavior, the visual lint, and the written philosophy in `DESIGN.md` and the [rules](/docs/rules). Each page records a rule that already lives in tokens, Stylus, components, lint, or `DESIGN.md`. Where Aura has no rule yet, the page says so and stops. The [Handbook](/docs/handbook) shows how styles and composition are wired in this site. The [Rules](/docs/rules) are the same constraints, packaged for agents. Foundations are the reading copy of both. ## Pages [#pages] | Foundation | Status | | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | [Accessibility](/docs/foundations/accessibility) | Specified. Perceivable, operable UI, APCA targets, focus, 17px fields, reduced motion. | | [Color](/docs/foundations/color) | Specified. 12-step accent and gray scales, status pairs, semantic aliases. | | [Components](/docs/foundations/components) | Specified. Registry ownership, variants, and the rule against restyling primitives at the call site. | | [Data visualization](/docs/foundations/data-visualization) | Chart families in the Charts section. Series tokens `--chart-1`–`--chart-5`, gray grid and ticks, 250ms motion. | | [Figma](/docs/foundations/figma) | Not defined yet. Aura ships source, not a Figma library. | | [Icons](/docs/foundations/icons) | Specified. Radix icons as type, `icon` class, gap on the container. | | [International design](/docs/foundations/international) | Not defined yet. A few components accept `dir`; there is no layout spec. | | [Layout](/docs/foundations/layout) | Specified. 13px grid, containers, `.aureole`. | | [Depth and elevation](/docs/foundations/elevation) | Specified. Radius tied to spacing, tonal sheets, borders at steps 6–8. `DESIGN.md` §6 keeps this as its own system. | | [Motion](/docs/foundations/motion) | Specified. CSS tokens, compositor-friendly properties, reduced motion. | | [Patterns](/docs/foundations/patterns) | Specified. `asChild` composition, form wiring, section rhythm. | | [Theming](/docs/foundations/theming) | Specified. `prefers-color-scheme`, `.dark` status colors, theme color switcher. | | [Typography](/docs/foundations/typography) | Specified. Fluid `clamp()` scale, Gabarito, 17px root and form floor. | | [Voice and tone](/docs/foundations/voice) | Not defined yet. Consistency asks for one voice; a writing guide does not exist. | # International design (/docs/foundations/international) Not defined yet. Aura has no written spec for mirroring, locale-specific typography, bidirectional text, or international layout grids. A few components already accept a `dir` prop or render under Radix direction context (`SegmentedInput`, `Editable`, `FileUpload`, `AvatarGroup`, `AngleSlider`, `ActionBar`). Calendar, carousel, and pagination put `cn-rtl-flip` on directional chevrons, and calendar adds RTL rotate utilities for its previous and next icons. There is no `.cn-rtl-flip` rule in `main.css` or the styled system, and no foundation that says when a layout must mirror. Those call sites are component details. They are not an international design system. A future page should define the rule first, then point at the components that follow it. # Layout (/docs/foundations/layout) Layout in Aura starts from one length: 13px. Tailwind v4 reads `--spacing: 13px`, and the same length is the Stylus unit `aura` and the custom property `--aura`. Every spacing utility is that unit times the number in the class. `p-4` is 52px. `gap-0.5` is 6.5px. `p-1.5` is 19.5px. Depth, radius, and surface stacking are specified separately in [Depth and elevation](/docs/foundations/elevation). They share this grid. ## Spacing [#spacing] Use half steps only: `1`, `1.5`, `2`, `2.5`, `3`, `3.5`, and so on. Increments such as `0.2`, `0.4`, or `p-1.2` are outside the scale. Arbitrary values such as `p-[16px]` are outside it too. A request for roughly 20px maps to `1.5` (19.5px). | Utility | Result | | ------- | ------ | | `1` | 13px | | `1.5` | 19.5px | | `2` | 26px | | `2.5` | 32.5px | | `3` | 39px | | `3.5` | 45.5px | | `4` | 52px | `shadcn/no-arbitrary-values` enforces the scale in lint. Affected utilities include margin, padding, gap, `space-x`, `space-y`, and the size family (`h`, `w`, `min-h`, `max-w`, `size`, and the rest). Major sections use a large vertical gap: `gap-3.5` (45.5px) or `gap-4` (52px). Dense registry rows use `px-1` (13px) or `px-1.5` (19.5px). There is no `1.25` step. Stylus helpers in `packages/styled-system/src/fundations/_spacing.styl` (`.pad`, `.aura`, `.mb13`, `.mt13`, `.ml13`, `.mr13`) are the older names for the same unit. `.pad` is `aura * 3.5` on top (45.5px), `var(--aura)` on the sides, and `aura * 1.5` on the bottom, collapsing to `aura * 2` on top below 767px. The compiled `.pad` in `main.css` matches those pixel values. ## Containers [#containers] Every section sits in a container that has padding, margin, and a max-width. A project keeps at most five container types. The registry set is five widths plus the shared centering class: | Class | Max width | Source | | -------- | --------- | ------------------------------------ | | `.smish` | 250px | `tokens/_container.styl`, `main.css` | | `.smosh` | 440px | same | | `.smash` | 740px | same | | `.smush` | 1032px | same | | `.smesh` | 1600px | same | `.aura-container`, `.smish`, `.smosh`, `.smash`, and `.smush` are `margin: 0 auto`. `.smesh` sets max-width only in the compiled CSS. Breakpoints in Stylus are `$small = 767px` and `$large = 1155px`. `body` has `min-width: 320px`. ## Grid [#grid] `.aureole` is the page grid. ```css .aureole { display: grid; grid-gap: var(--aura); grid-template-columns: repeat(3, minmax(0, 1fr)); } ``` Column counts are modifier classes: `.one`, `.two`, `.four`, `.five`, `.six`, `.twelve`. Spans are `.span-1` through `.span-12`. Below 767px, `.aureole:not(.fixed)` becomes one column, and spans that are not `.fixed` become `span 1`. From 767px up, `.aureole.reverse .one` and `.two` swap order. The Stylus grid (`layout/_grid.styl`) also defines `.aureole.blog` (`2fr 1fr`) and `.aureole.docs` (`1fr 4fr`). Those two templates are not in the compiled `packages/registry/styles/main.css`. Use the classes the CSS file actually emits unless you are compiling the Stylus source yourself. `.halo` is a wrapping row flex, full width. `.reverse` sets `flex-direction: row-reverse`. ## Related [#related] * [Layout and spacing rules](/docs/rules/fundations-layout-spacing) * [Depth and elevation](/docs/foundations/elevation) * [Handbook — Styling](/docs/handbook/styling) * `DESIGN.md` §5 and §8 # Motion (/docs/foundations/motion) Motion clarifies cause and effect. It is interruptible and driven by input. Aura prefers CSS (`@theme` animation tokens and `@keyframes` in `@layer components`) over the Web Animations API, and that API over a JS animation library. Properties that run on the compositor — `transform` and `opacity` — are the ones to animate. Height is the documented exception, and only for accordion and collapsible content, from `0` to the Radix content-height variable. ## Best practices [#best-practices] * Provide a reduced-motion variant. `.aura-overlay` sets `animation: none` and `transition: none` under `@media (prefers-reduced-motion: reduce)`. * Enter and exit content with opacity plus `transform: scale()`. Scrims can be opacity alone. * Interactive hover and active states use scale. Buttons in `main.css` go to `scale(1.03)` on hover and `scale(0.97)` on active. * Durations step in 250ms where the foundation rule applies. Easing follows the kind of change: `ease-in-out` for tooltips in the written rule, `cubic-bezier(0.16, 1, 0.3, 1)` for dialogs, `ease` for collapsible and accordion in the written rule, `cubic-bezier(0.4, 0, 0.6, 1)` for button color transitions in the written rule. * Skip autoplay that is not a skeleton or a similarly quiet loading state. The Stylus `.floating` keyframe (3s, infinite, `ease-in-out`, 15px vertical travel) and `.skeleton` (1s linear alternate between `--aura-skeleton-start` and `--aura-skeleton-end`) are the two looping animations in the foundation stylesheet. The tables below are the values in the stylesheets. They do not all match the 250ms rule. When you add motion, follow the rule. When you read an installed component, trust the file that component imports. ## Dialog and alert dialog [#dialog-and-alert-dialog] Scrims share `.aura-overlay` in `packages/registry/registry/default/styles/overlay.css`. Dialog content still uses `dialog.css` and `alert-dialog.css`: | Token | Duration | Easing | From → to | | ------------------------ | -------- | ------------------------------- | ------------------------------------------------------------------------------------ | | `.aura-overlay` | 150ms | `cubic-bezier(0.16, 1, 0.3, 1)` | opacity 0 → 1, `background-color: var(--aura-overlay)`, `backdrop-filter: blur(4px)` | | `--animate-content-show` | 150ms | `cubic-bezier(0.16, 1, 0.3, 1)` | opacity 0 and `scale(0.96)` → opacity 1 and `scale(1)` | Tooltip uses the same curve: show 150ms, hide 120ms, both scaling from `0.96` (`tooltip.css`). The docs-site copies under `apps/www/styles/` match the dialog pair. ## Accordion and collapsible [#accordion-and-collapsible] Registry files: | Token | File | Duration | Easing | | --------------------------------------------------------- | ------------------------ | --------------------------------- | -------------------------------------- | | `--animate-accordion-open` / `--animate-accordion-closed` | `styles/accordion.css` | 200ms | `cubic-bezier(0.645, 0.045, 0.355, 1)` | | Accordion chevron | same file | 200ms, rotate to 180deg when open | same curve | | `--animate-collapsible-down` | `styles/collapsible.css` | 250ms | `cubic-bezier(0.645, 0.045, 0.355, 1)` | | `--animate-collapsible-up` | `styles/collapsible.css` | 200ms | same curve | The copies in `apps/www/styles/` differ: accordion open and closed are 250ms `ease-in-out`, and both collapsible directions are 500ms `ease`. The [Handbook animations](/docs/handbook/animations) page documents those docs-site copies. The registry files are what `shadcn add` ships. Both implementations animate `height` to `var(--radix-accordion-content-height)` or `var(--radix-collapsible-content-height)`, which is the allowed layout exception. ## Buttons [#buttons] `.button` and its variants in `main.css` use one `transition` so the background fade and the scale both run: ```css transition: background-color 300ms cubic-bezier(0.4, 0, 0.6, 1), transform 250ms cubic-bezier(0.2, 0.8, 0.4, 1); ``` Hover (when not disabled): `transform: scale(1.03)`. Active: `transform: scale(0.97)` and `outline: var(--aura-outline)`. Keyboard focus uses the same outline on `:focus-visible`. Under `prefers-reduced-motion: reduce`, hover and active scales are `transform: none`. ## Reduced motion [#reduced-motion] Buttons, dialog, alert dialog, accordion, collapsible, tooltip, popover, sheet, sidebar, command, selection toolbar, action bar, file upload, mention, and the responsive dropdown each ship a `prefers-reduced-motion: reduce` block. Accordion also shortens the chevron transition to `0.01ms` under that query. `MessageScroller` uses `motion-reduce:transition-none` on its jump control. ## Related [#related] * [Animation rules](/docs/rules/fundation-animations) * [Handbook — Animations](/docs/handbook/animations) * [Accessibility](/docs/foundations/accessibility) * `packages/styled-system/src/fundations/_animation.styl` * `DESIGN.md` §1 and §7 # Patterns (/docs/foundations/patterns) Patterns in Aura are the ways components combine, not a separate visual language. Three are specified: Radix composition, the form system, and the spacing rhythm for sections and dense data. A pattern library of named page templates is not defined beyond that. ## Compose with asChild [#compose-with-aschild] Components sit on Radix primitives. `asChild` merges the primitive’s behavior onto your element instead of rendering the default one. The child has two jobs: spread incoming props onto the DOM node, and forward the ref. You can nest primitives (a tooltip and a dialog on one trigger) when each child still forwards both. Changing the element means you keep it operable. A trigger that becomes a link still needs to be focusable and respond to keyboard and pointer. The full walkthrough, including nested primitives, is the [composition handbook](/docs/handbook/composition). ## Forms [#forms] Forms are a pattern with a single error channel: 1. Hold state with `useFormDynamic(initialValues, formRef?)`. 2. Wrap fields in `<Form ref={formRef} onSubmit={...} errors={errors} id="...">`. Errors are not passed per field. `Form` matches `instancePath` to `field.name`. 3. Validate with `validateFormData(schema, formData.getValues())`. On failure, call `touchForm()` and pass `errors` to `Form`. 4. Submit with `<FormSubmit form={id} fetchStatus={...}>`. 5. For Select, Combobox, Editor, SignaturePad, and SortableList, write changes through `field.setValue`. That contract is the [form rule](/docs/rules/components-forms) and `DESIGN.md` appendix B. ## Section rhythm [#section-rhythm] | Situation | Pattern | | -------------------- | ---------------------------------------------------------------------------------------------- | | Major sections | Container (`.smish` … `.smesh`) plus `gap-3.5` or `gap-4` | | Editorial separation | Background step change (`gray-1` canvas, `gray-2` / `gray-3` bands) before a full-width rule | | Controls and dialogs | Borders at steps 6–8, focus via `--aura-outline` | | Data rows | `text-sm` cells, uppercase tracked headers, `px-1` or `px-1.5`, `ui-monospace` for ids | | Empty collections | `@aura/empty`: dashed `gray-6`, `gray-2` fill, title at `.h5`, primary `Button variant="fill"` | | Narrow navigation | Sidebar collapses into sheet or drawer | Asymmetric overlap — a `rounded-xl` panel with a negative margin and a stacking order — is described in `DESIGN.md` §5 as an editorial option. It is not a component. ## Related [#related] * [Handbook — Composition](/docs/handbook/composition) * [Handbook — Customization](/docs/handbook/customization) * [Components](/docs/foundations/components) * [Layout](/docs/foundations/layout) * `DESIGN.md` §4 and §5 # Theming (/docs/foundations/theming) A theme in Aura swaps hex values and keeps step roles. Step 9 is still the solid brand surface in the dark scheme. Step 12 is still primary text. The mechanism is CSS, not a parallel component skin. ## Scheme [#scheme] `packages/registry/styles/globals.css` sets the light scales on `:root`. `@media (prefers-color-scheme: dark)` reassigns accent and gray on `:root:not(.light)`. `.dark` repeats that same dark scale outside `@layer`, so a class toggle wins over the light `:root` values. Step 9 stays `#4015ca` in both schemes. The dark hexes are the Somos Gente Digital ramp. The light ramp is generated from accent `#4015ca`, gray `#7254cb`, and background `#ffffff`. `main` is always `background-color: var(--gray-1)`, which resolves to `#fcfaff` in light and `#100b21` in dark. Full tables are on the [Color](/docs/foundations/color) page. Status pairs change with the scheme. `.dark` and the dark media query set: | Token | `.dark` value | | -------------------- | ------------- | | `--info` | `#0D2157` | | `--info-contrast` | `#8CB4FF` | | `--success` | `#0B2E1E` | | `--success-contrast` | `#67CF9D` | | `--danger` | `#3C1405` | | `--danger-contrast` | `#FF9469` | | `--warning` | `#2A2402` | | `--warning-contrast` | `#EFE08E` | Light status values live on `:root` and on `@theme inline`. They are listed on the color page. An app that sets `.dark` gets the full Somos Gente Digital accent, gray, and status scales. `prefers-color-scheme: dark` does the same unless the root has class `light`. ## Theme color switcher [#theme-color-switcher] `@aura/theme-color-switcher` (`ThemeColorSwitcher.tsx`) is the tool for generating a new accent scale. It reads `next-themes` (`resolvedTheme === "dark"` → dark appearance) and seeds: | | Accent | Gray | Background | | ----- | --------- | --------- | ---------- | | Light | `#4015ca` | `#7254cb` | `#ffffff` | | Dark | `#4015ca` | `#7254cb` | `#100b21` | Those seeds are the switcher’s defaults, stored under `aura-theme-colors`. Light `:root` in `globals.css` is that generator pass (`--accent-9` is `#4015ca`). Dark `globals.css` keeps the Somos Gente Digital hexes instead of a second generator pass. `generateRadixColors` turns a seed into a 12-step scale. Components keep reading `--accent-` and `--gray-`. A single seed color can fill accent, gray, and background for both light and dark. `schemeFromSeed` keeps the seed hue, lowers chroma for the gray companion, and sets a light and a dark background. The switcher applies that scheme immediately and still lets light and dark be edited on their own. An image can supply the seed: the switcher averages the image’s pixels and runs the same scheme. Ladle preview colors in the same `globals.css` file (`--ladle-bg-color-primary`, `--ladle-color-primary`, and the rest) point at gray steps and `--primary`, so the story canvas follows the theme. ## What theming does not cover [#what-theming-does-not-cover] There is no token for “material” surfaces, blur levels, or a dark-mode shadow set. Depth stays the border and tonal system in [Depth and elevation](/docs/foundations/elevation). High-contrast, increased-contrast, and forced-colors modes are not specified. ## Related [#related] * [Color](/docs/foundations/color) * [Taste](/docs/taste) * `packages/registry/styles/globals.css` * `packages/registry/registry/default/components/ThemeColorSwitcher.tsx` * `DESIGN.md` §2 # Typography (/docs/foundations/typography) Primary type is fluid. Each heading and the body paragraph set `--min`, `--val`, and `--max`, and the element uses `clamp()`. Tailwind `text-xl`, `text-2xl`, and the rest of that ramp are for something else; they are not the Aura heading scale. Small fixed UI text may use `text-sm` (0.875rem) or `text-xs` (0.75rem), and those two utilities stay off editable fields. ## Scale [#scale] Shipped in `packages/registry/styles/main.css`. `--val` is `4.03vw` (the file writes `4.029999999999999vw`). | Element | `--min` | `--val` | `--max` | | ------------------------- | ------------ | -------- | ---------- | | `h1`, `.h1` | `1.9838rem` | `4.03vw` | `3.052rem` | | `h2`, `.h2` | `1.58665rem` | `4.03vw` | `2.441rem` | | `h3`, `.h3` | `1.482rem` | `4.03vw` | `2.28rem` | | `h4`, `.h4`, `blockquote` | `1.26945rem` | `4.03vw` | `1.953rem` | | `h5`, `.h5` | `1.17225rem` | `4.03vw` | `1.563rem` | | `h6`, `.h6` | `1.0625rem` | `4.03vw` | `1.25rem` | | `p`, `.p` | `1rem` | `4.03vw` | `1rem` | The clamp selector lists `body h1` through `body h6`, `body p`, and `body .h1` through `body .h6`. Class `.p` declares the same custom properties for a paragraph-sized node that is not a `p`. `.small` is 14px medium with line-height `1.4rem`. `.xs` is the micro style: 12px, semibold, line-height 16px. Stylus (`fundations/_typo.styl`) still computes `--min` as a fraction of the visual scale (`h1`–`h4` at 0.65, `h5` at 0.75, `h6` at 0.85) and sets `--val` to `3.03vw + 1rem`. The maxes match the CSS table (`tokens/_typography.styl`: `visualScale-h1 = 3.052rem` down to `visualScale-base = 1rem`). The compiled registry CSS is what consumers load; its `--val` is `4.03vw` without the extra `1rem`. `--min` and `--max` are `rem`, so they follow the user’s browser font size. Heading line-height should stay between 1.1 and 1.3. `html` sets `line-height: 1.21053`. ## Fonts [#fonts] ```css --font-sans: var(--font-gabarito, "Gabarito"), sans-serif; --aura-font-stack: var(--font-gabarito, "Gabarito"), -apple-system, BlinkMacSystemFont, "Segoe UI", "Roboto", "Oxygen", "Ubuntu", "Cantarell", "Fira Sans", "Droid Sans", "Helvetica Neue", sans-serif; --aura-font-quotes: serif; ``` Next apps load Gabarito with `next/font/google` (`subsets: ["latin"]`, `variable: "--font-gabarito"`) and put that class on `<html>`. `var(--font-gabarito, "Gabarito")` uses the loaded face when the variable is set, and the named family otherwise. Registry `main.css` starts the same stack at `"Gabarito"` with the system fallbacks, for apps that are not on `next/font`. `html` and `pre` use `--aura-font-stack`. `blockquote` uses `--aura-font-quotes`, uppercase, weight 600, and the `h4` clamp. Paragraphs take `margin: var(--aura) 0` (13px). `ul:not(.default)` drops list markers and padding. `html` also sets `-webkit-font-smoothing: antialiased`, `text-size-adjust: 100%`, and `text-rendering: optimizelegibility`. The base layer sets `html { font-size: 17px; }`. That is why `1rem` on a control already meets the mobile floor. ## Roles [#roles] | Role | Treatment | | ------------------------------- | ------------------------------------------------------------------------------------------------- | | Display / statement | `.h1`–`.h3`. Optional `letter-spacing: -0.02em` on the largest display, line-height still 1.1–1.3 | | Section titles | `.h4`–`.h6` | | Dense cells | `text-sm` (0.875rem) | | Micro-labels and column headers | `text-xs` or `text-sm`, uppercase, `letter-spacing: 0.05em` | | Identifiers | `ui-monospace` (or the app’s monospace stack) | ## Form floor [#form-floor] Editable `input`, `textarea`, and `select` use `font-size: max(1rem, 17px)` in an unlayered rule in both `globals.css` and `main.css`. Checkbox, radio, range, file, hidden, button, submit, reset, image, and color inputs are exempt. `text-sm` and `text-xs` on an editable control are a lint and a product failure: iOS Safari zooms on focus below about 16–17px. ## Related [#related] * [Typography specimen](/docs/components/typography) * [Typography rules](/docs/rules/fundations-typography) * [Accessibility](/docs/foundations/accessibility) * [Icons](/docs/foundations/icons) * `packages/styled-system/src/tokens/_typography.styl` * `DESIGN.md` §3 # Voice and tone (/docs/foundations/voice) Not defined yet. Aura’s consistency principle says every team speaks to the user in the same way, visually and in writing. That sentence is the whole writing rule. There is no terminology list, no tone scale, no capitalization guide, and no content pattern for errors, empty states, or buttons. What does exist, and belongs to other foundations: * Product principles name the attitude of the system: accessible, consistent, reusable, shareable, user control, forgiveness, and a sense of stability. See [Principles](/docs/rules/principles). * Button and empty-state structure is specified. The words inside them are not. See [Patterns](/docs/foundations/patterns). * Type size, case, and tracking for labels are visual rules. See [Typography](/docs/foundations/typography). A voice and tone page should be written from a real guide in the repo. Until that guide exists, this page stays empty on purpose. # Animations (/docs/handbook/animations) Component enter/exit and overlay animations are defined as CSS custom properties and keyframes. The app imports the animation styles in `@layer components` and components reference them via `data-[state=open]:animate-` (or equivalent state). ## Where animations live [#where-animations-live] In the www app, these four files are imported inside `@layer components` in [apps/www/app/globals.css](apps/www/app/globals.css) (lines 278–281): `../../../packages/registry/registry/default/styles/overlay.css` (shared scrim) * `../styles/accordion.css` * `../styles/alert-dialog.css` * `../styles/collapsible.css` * `../styles/dialog.css` Theme blocks use `@theme animations`. Keyframes are defined in `@layer components`. Tailwind v4 ignores an unknown word after `@theme`, so the earlier `@theme animatons` typo still registered `--animate-` tokens; sheet and alert-dialog now use the correct spelling. ## Accordion [#accordion] File: `apps/www/styles/accordion.css` | Token | Keyframes | Duration | Easing | | ---------------------------- | -------------------- | -------- | ----------- | | `--animate-accordion-open` | `slideDownAccordion` | 250ms | ease-in-out | | `--animate-accordion-closed` | `slideUpAccordion` | 250ms | ease-in-out | slideDownAccordion: `height: 0` → `height: var(--radix-accordion-content-height)` * slideUpAccordion: `height: var(--radix-accordion-content-height)` → `height: 0` Uses Radix's content-height variable for smooth height animation (allowed for collapsible/accordion in the animation foundation). ## Alert dialog and Dialog [#alert-dialog-and-dialog] Files: `apps/www/styles/alert-dialog.css`, `apps/www/styles/dialog.css` Modal scrims do not use those overlay utilities. `AlertDialog`, `Dialog`, `Sheet` (including the mobile `Sidebar` sheet), `Drawer`, `Command`, and `ComboboxBackdrop` share `.aura-overlay` from `packages/registry/registry/default/styles/overlay.css`. That class sets `background-color: var(--aura-overlay)` and a 4px `backdrop-filter` blur. `--aura-overlay` is `rgb(16 11 33 / 0.08)` (dark gray-1, `#100B21`, at 8%) in both light and dark. It is not `var(--gray-1)`, because gray-1 is near-white in light mode. The enter fade is opacity 0 → 1 in 150ms with `cubic-bezier(0.16, 1, 0.3, 1)`. `@media (prefers-reduced-motion: reduce)` sets `animation: none` and `transition: none`. Content tokens stay on the dialog stylesheets: | Token | Keyframes | Duration | Easing | | ------------------------ | ------------- | -------- | ----------------------------- | | `--animate-content-show` | `contentShow` | 150ms | cubic-bezier(0.16, 1, 0.3, 1) | * contentShow: `opacity: 0` and `transform: scale(0.96)` → `opacity: 1` and `transform: scale(1)` `DialogContent` and `AlertDialogContent` use `data-[state=open]:animate-content-show`. Each overlay keeps its own `z-50`. ## Collapsible [#collapsible] File: `apps/www/styles/collapsible.css` | Token | Keyframes | Duration | Easing | | ---------------------------- | ---------------------- | -------- | ------ | | `--animate-collapsible-down` | `slideDownCollapsible` | 500ms | ease | | `--animate-collapsible-up` | `slideUpCollapsible` | 500ms | ease | * slideDownCollapsible: `height: 0` → `height: var(--radix-collapsible-content-height)` * slideUpCollapsible: `height: var(--radix-collapsible-content-height)` → `height: 0` ## Usage in components [#usage-in-components] Apply the animation tokens with Tailwind (or equivalent) using the state that Radix exposes, e.g.: * Scrim: class `aura-overlay` (fade is inside `overlay.css`, not a per-component utility) * Content: `data-[state=open]:animate-content-show` * Accordion/Collapsible content: use the corresponding open/closed or down/up tokens on the content wrapper that has the height transition. Animations follow the Aura animation foundation: compositor-friendly properties (`transform`, `opacity`; height only for collapsible/accordion), and you should respect `prefers-reduced-motion` where applicable (e.g. reduced or no animation for users who request it). # Composition (/docs/handbook/composition) Aura components are built on [Radix UI](https://www.radix-ui.com/primitives/docs/guides/composition). Use the `asChild` prop to compose a primitive's behavior onto your own element or React component instead of the default DOM element. ## asChild (Radix UI) [#aschild-radix-ui] All Radix primitive parts that render a DOM element accept `asChild`. When `asChild` is `true`, Radix does not render its default element; it clones the single child and merges the props and behavior needed for that part (e.g. trigger click, focus, aria attributes). Reference: [Radix UI — Composition](https://www.radix-ui.com/primitives/docs/guides/composition). ### Changing the element type [#changing-the-element-type] You can change the underlying element. For example, `Tooltip.Trigger` defaults to a `button`; with `asChild` you can use a link: ```tsx <Tooltip.Root> <Tooltip.Trigger asChild> <a href="https://www.radix-ui.com/">Radix UI</a> </Tooltip.Trigger> <Tooltip.Portal>…</Tooltip.Portal> </Tooltip.Root> ``` If you change the element type, you are responsible for keeping it accessible and functional (e.g. the trigger must remain focusable and respond to pointer and keyboard). ### Composing with your own React components [#composing-with-your-own-react-components] Pass your component as the single child and set `asChild` on the Radix part. Two requirements: 1. Spread props — Radix passes props and event handlers to the child. Your component must forward them to the underlying DOM node (e.g. `<button {...props} />`). 2. Forward ref — Radix may attach a ref (e.g. for measurement). Use `React.forwardRef` and pass the ref to the DOM node. ```tsx const MyButton = React.forwardRef((props, forwardedRef) => ( <button {...props} ref={forwardedRef} /> )); <Dialog.Trigger asChild> <MyButton>Open dialog</MyButton> </Dialog.Trigger> ``` This is the usual way to use Aura (or your own) buttons and links as Dialog, AlertDialog, Tooltip, or Dropdown triggers. ### Composing multiple primitives [#composing-multiple-primitives] You can nest `asChild` so one element receives behavior from several primitives. Order matters: the outermost Radix part wraps the next, and the innermost child is your element. Example: a custom button that opens a dialog and shows a tooltip: ```tsx <Dialog.Root> <Tooltip.Root> <Tooltip.Trigger asChild> <Dialog.Trigger asChild> <MyButton>Open dialog</MyButton> </Dialog.Trigger> </Tooltip.Trigger> <Tooltip.Portal>…</Tooltip.Portal> </Tooltip.Root> <Dialog.Portal>…</Dialog.Portal> </Dialog.Root> ``` Same idea applies for other trigger-based primitives (e.g. Menu, Popover). Keep the underlying element focusable and interactive. ## Similar ideas in other libraries [#similar-ideas-in-other-libraries] Libraries like [Base UI](https://base-ui.com/react/handbook/composition) use a `render` prop instead of `asChild` to achieve the same goal: the part renders your custom component and passes props/ref to it. The mental model is the same — one child, ref and props forwarded, and the primitive controls behavior. Aura uses Radix, so follow the Radix composition guide above; the Base UI composition docs are useful for comparison if you switch or integrate with another system. # Customization (/docs/handbook/customization) Aura components built on Radix UI can be used uncontrolled (default) or controlled. You can drive open/close state from your own state and react to change events. This page summarizes the patterns; for full API details see [Radix UI](https://www.radix-ui.com/primitives) and, for comparison, [Base UI — Customization](https://base-ui.com/react/handbook/customization). ## Controlling with state [#controlling-with-state] By default, components like Dialog, AlertDialog, Tooltip, and Collapsible are uncontrolled: they manage open state internally and open/close in response to the trigger and built-in behavior (e.g. Escape, outside click). To control them, pass your own state into the root component: * `open` — boolean, whether the overlay or content is open. * `onOpenChange` — callback that receives the next open value (and in some primitives, event details). Update your state here so the component stays in sync. Example: open a dialog after a timeout, without a user clicking a trigger: ```tsx const [open, setOpen] = React.useState(false); React.useEffect(() => { const t = setTimeout(() => setOpen(true), 1000); return () => clearTimeout(t); }, []); return ( <Dialog.Root open={open} onOpenChange={setOpen}> <Dialog.Portal> <Dialog.Overlay /> <Dialog.Content>Opened programmatically.</Dialog.Content> </Dialog.Portal> </Dialog.Root> ); ``` Controlled state also lets you read or influence open state from outside (e.g. close from a parent, or sync with URL or analytics). ## Change events [#change-events] Handlers such as `onOpenChange` are called when the component would change state (e.g. user presses Escape, clicks outside, or clicks the trigger). In Radix, the signature is typically `onOpenChange(open: boolean)`. Some primitives or wrappers may pass a second argument with event details (e.g. reason, native event). Use that when available to branch behavior (e.g. only run logic when the reason is `escape-key` or `pointer-down-outside`). Check the Radix docs for each primitive’s callback shape. ## Preventing or customizing a change [#preventing-or-customizing-a-change] * Radix: There is no built-in `cancel()` on the event. To “prevent” a change, use the component in controlled mode: keep `open` and in `onOpenChange` decide whether to call your state setter. If you don’t update state (or set it to the same value), the component effectively doesn’t change. * Base UI documents `eventDetails.cancel()` to stop the internal state update; that pattern is library-specific. In Aura (Radix), controlling state and not updating it is the equivalent. ## Propagation (e.g. Escape key) [#propagation-eg-escape-key] In overlays like Dialog or Tooltip, Escape often closes the topmost overlay and may stop propagation so parent overlays don’t all close. In Radix, this behavior is built in; customization options depend on the primitive. Base UI documents `eventDetails.allowPropagation()` to let the DOM event propagate so a parent can also close. If you need similar behavior with Radix, check the specific primitive’s docs and props for escape or focus behavior. ## Escape hatches [#escape-hatches] When you need to prevent the default behavior of a React event (e.g. `onClick`, `onKeyDown`) that the primitive also handles, you can call `event.preventDefault()` or `event.stopPropagation()` in your handler. Use sparingly and only when the primitive doesn’t expose a prop for the behavior you want. For Radix, see the relevant primitive’s API for supported props and events. ## Summary [#summary] | Need | Approach in Aura (Radix) | | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | Open/close from code or external state | Use controlled `open` and `onOpenChange`. | | Run logic when open state changes | Implement it inside `onOpenChange` (and use `open` if you need to read current state). | | “Cancel” a close or open | Use controlled state and in `onOpenChange` don’t update state when you want to keep the current state. | | Customize Escape or propagation | Check the Radix primitive’s docs for escape/focus props. | | Override a specific event | Use React event handlers and `preventDefault`/`stopPropagation` as needed; prefer primitive props when available. | # Handbook (/docs/handbook) The Handbook is the reference for how Aura handles styling, animations, composition, and customization. Use it when you need to align with the design system's foundations or extend components. The narrative spec for each foundation — color, type, layout, icons, motion, and the rest — is the [Foundations](/docs/foundations) section. These handbook pages stay the wiring notes. ## Styling [#styling] Where design tokens and shared styles live: registry `main.css` (layout, typography, utilities) and `globals.css` (`@theme`, color scales, base layer). Use these for consistent spacing, colors, and layout across apps. [Styling reference →](/docs/handbook/styling) ## Animations [#animations] Component enter/exit and overlay animations are defined as CSS tokens and keyframes. The accordion, alert-dialog, collapsible, and dialog styles are imported in the app globals and referenced by components via `data-[state=open]:animate-`. [Animations reference →](/docs/handbook/animations) ## Composition [#composition] Use Radix's `asChild` to compose primitives with your own elements or components (e.g. a custom button as a dialog trigger). Components must spread props and forward refs; you can nest multiple primitives (e.g. tooltip + dialog on the same trigger). [Composition guide →](/docs/handbook/composition) ## Customization [#customization] Control open/close state with `open` and `onOpenChange`, handle change events for escape or outside click, and use controlled state when you need to open dialogs or popovers without a trigger or from external logic. [Customization guide →](/docs/handbook/customization) ## Full documentation for LLMs [#full-documentation-for-llms] A single plain-text dump of the site documentation for crawlers and LLMs is available at [https://auradesignsystem.com/llms-full.txt](https://auradesignsystem.com/llms-full.txt). # llms.txt (/docs/handbook/llms.txt) This page redirects to [llms-full.txt](/llms-full.txt). If you are not redirected, [open the full documentation](/llms-full.txt). # Styling (/docs/handbook/styling) Aura's styling is split between the registry's shared layer and the app's themed entry. Use the registry styles for design tokens, layout, and typography; use globals for Tailwind theme and color scales. ## Registry styles [#registry-styles] ### main.css [#maincss] Path: `packages/registry/styles/main.css` This file holds the shared design-token and layout layer used across Aura. Root tokens (`:root`): `--aura` (13px base), `--aura-font-stack`, `--aura-font-quotes`, `--aura-grey`, `--aura-bg`, `--aura-text-primary`, `--aura-text-primary-inverse`, accent tokens (`--aura-accents-primary`, `--aura-accents-success`, `--aura-accents-info`, `--aura-accents-warning`, `--aura-accents-danger` and `-bg` variants), `--aura-input-radius`, `--aura-button-radius`, `--aura-input-bg`, `--aura-input-placeholder-color`, `--aura-input-border-color`, `--aura-radius`, `--aura-opacity`, `--aura-outline`, `--aura-button-hover`, `--aura-link`, `--aura-link-hover`, `--aura-selector`, `--aura-loader`, `--aura-skeleton-start`, `--aura-skeleton-end`. * Layout: `.valign` (flex center column), `.fluid` (width 100%), `.halo` (flex row wrap), `.reverse`, `.aureole` (grid with `.one` … `.twelve` columns), `.span-1` … `.span-12`, responsive behavior for small viewports; `.aura-container`, `.smish`, `.smosh`, `.smash`, `.smush`, `.smesh` (max-width containers). * Typography: Fluid `clamp(var(--min), var(--val), var(--max))` on `body h1`–`h6`, `p`, and `.h1`–`.h6`, `.p`; each heading sets `--min`, `--val`, `--max`; `blockquote` shares the h4 scale; `p` margin and `blockquote` styling. * Utilities: `.truncate`, `.disabled` and input/button disabled opacity, `.typeahead`, `.action`, `.unset`, `.hide-small` / `.hide-medium` / `.hide-large` (media queries), `.warning` / `.info` / `.danger` / `.success` and `-text` variants. * Other: `.pad`, `.aura`, `.inputer`, `.skeleton` (loading animation). ### globals.css [#globalscss] Path: `packages/registry/styles/globals.css` This is the Tailwind/themed entry. It imports Tailwind and defines what the theme and base layer use. * `@theme inline`: `--spacing: 13px`, `--font-sans`, semantic colors (`--info`, `--success`, `--danger`, `--warning` and `-contrast`), radius scale (`--radius-sm` … `--radius-xl`), and Tailwind color mappings for `gray-`, `accent-`, and semantic tokens (`--primary`, `--primary-foreground`, etc.). * `:root`: 12-step scales `--accent-1`–`--accent-12`, `--accent-a1`–`--accent-a12`, `--accent-contrast`, `--accent-surface`, `--accent-indicator`, `--accent-track`; same for `--gray-`; `--primary`, `--primary-foreground`, `--secundary`, `--secundary-foreground`; Aura tokens (`--aura`, `--aura-font-stack`, `--aura-bg`, `--aura-text-primary`, input/button/loader/skeleton mappings). Dark mode: `@media (prefers-color-scheme: dark)` overrides for accent and gray scales. * `@layer base`: Imports `main.css` and default component styles (accordion, alert-dialog, collapsible, dialog, sidebar); `html` font-size, `main` background, `.dark` semantic overrides. ## How to use them [#how-to-use-them] * In an app: Import or layer the registry `globals.css` so the theme and base layer (including main.css) apply. Your app's own `globals.css` can then add or override (e.g. import component animation CSS in `@layer components` as in the www app). * Tokens: Use `--spacing` and the radius/color tokens from `@theme` and `:root` for margins, padding, borders, and backgrounds so Tailwind and custom CSS stay consistent. See [Taste](/docs/taste) for the spacing scale and color workflow. * Layout: Use `.aureole` and `.span-` for grids, and `.smish`–`.smesh` for section containers, per the layout and spacing rules. Typography: Prefer semantic classes `.h1`–`.h6`, `.p` (or the elements themselves) so fluid sizing and line-height apply; avoid Tailwind text-size utilities for primary copy. # Aura agent surface (/docs/rules/aura-agent-surface) # Aura agent surface [#aura-agent-surface] ## Installation [#installation] ```bash pnpm dlx shadcn@latest add @aura/rule-aura-agent-surface ``` ## Ownership [#ownership] | Layer | Owns | Does not own | | --------------------------------------- | --------------------------------------------------- | ----------------------------------------------- | | `DESIGN.md` | Narrative design SoT (tokens, theme, product voice) | Step-by-step agent procedures | | `.cursor/rules/` | MUST / SHOULD / NEVER guardrails for agent behavior | Install recipes, long how-tos, wiki write loops | | `.cursor/skills/` / `.agents/skills/` | Persistence and technical execution | Soft product principles | ## Invariants (Keep) [#invariants-keep] These stay encoded in foundation rules and machine-checked where lint allows. Do not weaken them when editing rules or skills. 12-step chromatic scale (`--accent-`, `--gray-`) with APCA contrast roles for steps 11–12 on step 2. * Fluid typography via `clamp()` and a global ≥ 17px floor on editable form controls. * Strict 13px spacing base (`unit * 13px`). * Icons use `className="icon"` only (type inheritance); no horizontal icon margins inside gap-owning controls. * Project Brain lives in `wiki/obsidian-{suffix}/` with `00-General/Internal-Progress.md` updated after each advance. ## Upstream shadcn skill (merge) [#upstream-shadcn-skill-merge] Installed via `pnpm dlx skills add shadcn/ui` into `.agents/skills/shadcn` (and `migrate-radix-to-base`). Use it for CLI, registry search/docs, composition discovery, and presets. When the shadcn skill conflicts with Aura Keep / foundation rules, Aura wins: | Topic | Prefer Aura | Use shadcn skill for | | ---------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | Icons | `@radix-ui/react-icons` + `className="icon"`; no `ml-`/`mr-` on icons in `Button`/`Badge` | Component discovery; ignore `data-icon` / Lucide defaults unless the installed component API requires them | | Forms | `useFormDynamic` + `Form` / `FormField` + `validateFormData` (skill `aura-forms`) | `FieldGroup` / `Field` only when the Aura form stack is absent | | Spacing | 13px scale (`gap-0.5` = 6.5px, `gap-2` = 26px) | `gap-` over `space-y-` (aligned) | | Color | `--accent-` / `--gray-` (+ semantic) | No raw palette (aligned); map shadcn semantics onto Aura tokens | | Typography | Fluid `.h1`–`.p`; no `text-xl` on primary copy; inputs ≥ 17px | Layout/`cn()` patterns that do not fight the floor | | Restyle | Variants/sizes; `@shadcn/lint` `no-restyle` | `className` for layout/width only (aligned) | Do not vendor the shadcn skill into `packages/registry` / `sync-skills.ts`. Blueprint installs it the same way as gdp-ts. ## Routing [#routing] * UI token questions → `DESIGN.md`, then foundation rules under `.cursor/rules/fundation`. shadcn CLI / registry / presets / component docs → skill `shadcn` (`.agents/skills/shadcn`). * After UI edits → skill `verify-aura-ui` (`pnpm lint`, clear `@shadcn/lint` debt you introduced). * After structural or API advances → skill `update-project-brain`. * Porting external UI into Aura → skill `port-component-to-aura`. * Aura form composition → skill `aura-forms` (guardrails in `components-forms.mdc`). * Monorepo DS edits in this repo → skills `aura-constraints` / `aura-verification` + root `AGENTS.md`. # Form guardrails (/docs/rules/components-forms) # Aura form guardrails [#aura-form-guardrails] ## Installation [#installation] ```bash pnpm dlx shadcn@latest add @aura/rule-components-forms ``` Forms use useFormDynamic for state, Form for error distribution, and validateFormData from `@/utils/web-validation`. Schema property names must match field names so errors match by `instancePath`. * MUST: Build forms with `useFormDynamic(initialValues, formRef?)` and pass fields from `getFields()` / `field(name)` into Form field components. * MUST: Validate with `validateFormData(schema, formData.getValues())` and pass returned `errors` to `<Form>`. On failure call `formData.touchForm()`. * MUST: Use Form field components (`FormField`, `FormSwitch`, `FormCheckbox`, groups) per control type; do not pass `errors` into each field. * MUST: Keep editable controls ≥ 17px (see typography guardrails). Do not override control padding via call-site `className`. * SHOULD: Use `FormAlert` for form-level errors when `fetchStatus === "error"`. Procedures and full submit examples live in skill `aura-forms`. # DESIGN.md (narrative spec) (/docs/rules/design-md) # Aura DESIGN.md [#aura-designmd] ## Installation [#installation] ```bash pnpm dlx shadcn@latest add @aura/rule-design-md ``` `DESIGN.md` at the repo root is the narrative design specification for Aura (theme, color roles, typography, 13px grid, motion, product principles). * MUST: When implementing UI, aligning with brand, or reasoning about Aura tokens, read and follow `DESIGN.md` together with foundation rules under `.cursor/rules/`. * SHOULD: Prefer tokens and patterns in `DESIGN.md` over ad-hoc styling or one-off hex values. * MUST NOT: Duplicate long design tables into rules or skills. Rules state guardrails; skills run procedures; `DESIGN.md` holds the narrative detail. # Animation guardrails (/docs/rules/fundation-animations) # Animation guardrails [#animation-guardrails] ## Installation [#installation] ```bash pnpm dlx shadcn@latest add @aura/rule-fundation-animations ``` * MUST: Honor `prefers-reduced-motion` with a reduced variant. * MUST: Prefer CSS (`@theme` animation tokens + `@keyframes` in `@layer components`) over Web Animations API or JS libraries. * MUST: Animate `transform` and `opacity` only. Avoid layout props (`top`/`left`/`width`/`height`) except accordion/collapsible height to `var(--radix--content-height)`. MUST: Set `transform-origin` so motion starts where it physically should. * MUST: Enter/exit content with `opacity` + `transform: scale()`. Overlays SHOULD use opacity only. * MUST: Keep motion interruptible and input-driven (no decorative autoplay). * SHOULD: Interactive hover/active use `scale(1.03)` / `scale(0.97)` with `transition: transform …`. * SHOULD: Use \~250ms steps; match easing to the change (tooltips `ease-in-out`, dialogs `cubic-bezier(0.16, 1, 0.3, 1)`, accordion `ease`, buttons `cubic-bezier(0.4, 0, 0.6, 1)`). * SHOULD: Animate only to clarify cause/effect or add deliberate delight. # Icon guardrails (/docs/rules/fundation-icons) # Icon guardrails [#icon-guardrails] ## Installation [#installation] ```bash pnpm dlx shadcn@latest add @aura/rule-fundation-icons ``` * MUST: Use an icon library. Default is `@radix-ui/react-icons`. Prefer a single library; if two, Radix plus one other. * MUST: Use `className="icon"` on every icon. Never `size`, `width`, or `height` props. Size via typography (`icon`, `icon h4`, `icon h1`). * MUST: Space icon from label with container `gap` (own rows use `gap-0.5`). Never `ml-` / `mr-` / `mx-` / `ms-` / `me-` on the icon (`aura/no-icon-margin`). MUST: Inside `Button` and `Badge`, add no icon gap classes — the control owns gap. * EXCEPTION: `ml-auto` / `mr-auto` for layout push only. # Color guardrails (/docs/rules/fundations-colors) # Color guardrails [#color-guardrails] ## Installation [#installation] ```bash pnpm dlx shadcn@latest add @aura/rule-fundations-colors ``` Narrative and step tables live in `DESIGN.md` §2. This rule only constrains agent behavior. * MUST: Use `--accent-{1–12}` and `--gray-{1–12}` (and alpha variants `--accent-a`, `--gray-a`). Prefer semantic tokens (`--primary`, `--accent-surface`, `--accent-contrast`, …) when available. * MUST: Map roles by step — 1–2 backgrounds, 3–5 interactive fills, 6–8 borders/focus, 9–10 solid brand, 11–12 text. * MUST: Keep steps 11–12 at APCA Lc 60 / Lc 90 targets on step 2 backgrounds. * MUST NOT: Ship one-off hex or raw palette utilities (`bg-pink-500`, marketing sample hex) as production source of truth. * SHOULD: Map `--primary` to `--accent-9`. On transparent defaults, hover may use step 3. # Spacing guardrails (/docs/rules/fundations-layout-spacing) # Spacing guardrails [#spacing-guardrails] ## Installation [#installation] ```bash pnpm dlx shadcn@latest add @aura/rule-fundations-layout-spacing ``` `--spacing` is 13px. Before any `m`/`p`/`gap`/`h`/`w`/`size` utility, compute `unit * 13px` (so `p-4` = 52px, not 16px). Detail in `DESIGN.md`. * MUST: Use the 13px base and 0.5-unit increments only (`1`, `1.5`, `2`, …). * NEVER: Use non-0.5 increments (`0.2`, `1.2`, …) or arbitrary pixel spacing (`p-[16px]`) unless the human explicitly asks. * MUST: Convert “about 20px” to `1.5` (19.5px), not `2` (26px). * MUST: Sections use defined containers (padding, margins, max-width). Prefer ≤ 5 container types per project. # Typography guardrails (/docs/rules/fundations-typography) # Typography guardrails [#typography-guardrails] ## Installation [#installation] ```bash pnpm dlx shadcn@latest add @aura/rule-fundations-typography ``` Scale tables and formula live in `DESIGN.md` §3. This rule only constrains agent behavior. * MUST: Size primary type with `clamp(var(--min), var(--val), var(--max))` via `h1`–`h6` / `.h1`–`.h6` / `p` / `.p`. * NEVER: Use Tailwind `text-xl`, `text-2xl`, `text-4xl`, etc. for primary copy. * EXCEPTION: `text-sm` / `text-xs` for fixed utility/meta text only — never on editable `input` / `textarea` / `select`. * MUST: Editable form controls stay ≥ 17px (`max(1rem, 17px)` or inherit the 17px root). Enforce globally in CSS (`styles/main.css` / unlayered globals), not only per component. * SHOULD: Keep `html { font-size: 17px; }` so `1rem` already meets the floor. * MUST: Use `rem` for `--min` / `--max`. Large headings SHOULD use line-height about 1.1–1.3. `blockquote` shares the `h4` scale. # Rules (/docs/rules) ## Rules [#rules] These rules define foundations and principles for the Aura Design System. You can install them via the registry or copy them into your project's `.cursor/rules/` directory. ```bash pnpm dlx shadcn@latest add @aura/rules ``` ### [Animation guardrails](/docs/rules/fundation-animations) [#animation-guardrails] Compositor-friendly motion, reduced-motion, theme animation tokens. Detail in DESIGN.md. ### [Aura agent surface](/docs/rules/aura-agent-surface) [#aura-agent-surface] Rules hold guardrails; skills hold execution. DESIGN.md is narrative SoT. Upstream shadcn skill is subordinate to Aura Keep invariants. ### [Color guardrails](/docs/rules/fundations-colors) [#color-guardrails] 12-step accent/gray scale and APCA contrast roles. Detail in DESIGN.md §2. ### [DESIGN.md (narrative spec)](/docs/rules/design-md) [#designmd-narrative-spec] Installs the Cursor rule and the project root DESIGN.md (narrative spec). Add with shadcn as @aura/rule-design-md. ### [Form guardrails](/docs/rules/components-forms) [#form-guardrails] Form system guardrails — useFormDynamic, Form, validateFormData. Procedures in skill aura-forms. ### [Icon guardrails](/docs/rules/fundation-icons) [#icon-guardrails] Radix icons via className="icon"; no horizontal margins inside gap-owning controls. ### [Product principles](/docs/rules/principles) [#product-principles] Non-visual Aura product principles that constrain product and UX choices. ### [Self-documenting system](/docs/rules/self-documenting-system) [#self-documenting-system] Guardrails for the Obsidian Project Brain and Bruno API parity. Write loops live in the update-project-brain skill. ### [shadcn lint](/docs/rules/shadcn-lint) [#shadcn-lint] Aura @shadcn/lint policy (no arbitrary values, no raw colors, no-restyle). Installs Cursor rule + eslint.aura-shadcn.mjs. Add with shadcn as @aura/rule-shadcn-lint or @aura/eslint-shadcn-lint. ### [Spacing guardrails](/docs/rules/fundations-layout-spacing) [#spacing-guardrails] Enforce Aura 13px spacing for Tailwind v4 ### [Typography guardrails](/docs/rules/fundations-typography) [#typography-guardrails] Fluid clamp() type scale and 17px floor for editable form controls. Detail in DESIGN.md §3. # Product principles (/docs/rules/principles) # Product principles [#product-principles] ## Installation [#installation] ```bash pnpm dlx shadcn@latest add @aura/rule-principles ``` These constrain product and UX choices. Visual tokens stay in `DESIGN.md` and foundation rules. ### Accessibility [#accessibility] Products must be usable by any user. Build for perception and operability. ### Consistency [#consistency] Teams share one objective and one voice with the user, visual and written. ### Reusable [#reusable] An hour spent on a component should prevent someone else from rebuilding it. ### Shareable [#shareable] Build with tools that let the team share the work. ### User control [#user-control] The user must feel in control of the product. ### Forgiveness [#forgiveness] The user must be able to change their mind or repeat a process. ### Perception of stability [#perception-of-stability] Even on complex platforms, processes should feel simple and familiar. # Self-documenting system (/docs/rules/self-documenting-system) # Self-documenting system (guardrails) [#self-documenting-system-guardrails] ## Installation [#installation] ```bash pnpm dlx shadcn@latest add @aura/rule-self-documenting-system ``` ## Directory authority [#directory-authority] * Vault: `wiki/obsidian-{suffix}/` (this repo: `wiki/obsidian-aura-design-project/`). * API catalog: `wiki/bruno-{suffix}/` (this repo: `wiki/bruno-aura-design-project/`). * Suffix: from `package.json` `name` with the first segment stripped (consumer apps). This monorepo vault is fixed as `obsidian-aura-design-project`. * MUST NOT: Use legacy root `.obsidian/` or `docs/` when a blueprint wiki exists. ## When you must persist [#when-you-must-persist] | Trigger | Required outcome | | --------------------------- | ------------------------------------------------------------------------------ | | Architectural decision | Obsidian note records the why and the library/pattern | | Complex fix (>2 iterations) | Note records root cause and file path | | API change | Bruno request + Obsidian logic note stay in parity | | Session advance / end | New ## Sessions entry and `pnpm brain:progress` passes when that script exists | ## Note shape [#note-shape] New notes under the vault MUST use frontmatter + short Summary / Context (see skill `update-project-brain` for the template and write steps). * MUST: Keep notes atomic (about 3–4 sentences per concept), use `[[wikilinks]]`, cite code paths, never write secrets (env names only). * MUST: Follow `[[Bootstrap]]` folders (`00-General`, `01-Identity`, `02-Documentation`, `03-Configuración`). ## Execution [#execution] How to create/update notes, sync Bruno, and append Internal Progress is skill `update-project-brain`. This rule only states the obligation. # shadcn lint (/docs/rules/shadcn-lint) # Aura + @shadcn/lint [#aura--shadcnlint] ## Installation [#installation] ```bash pnpm dlx shadcn@latest add @aura/rule-shadcn-lint ``` `@shadcn/lint` is the machine-checkable layer for Aura Tailwind policy. Rules and `DESIGN.md` guide agents; lint tells them how to fix UI. ## Guardrails [#guardrails] * MUST: After UI changes, run the project `lint` script (`pnpm lint`) and clear `@shadcn/lint` findings you introduced before finishing. Prefer zero new `shadcn/no-restyle` and `shadcn/no-arbitrary-values` on touched files. * MUST: Prefer theme tokens (`accent-`, `gray-`, semantic) over raw palette colors. * MUST: Prefer the Aura 13px spacing scale over arbitrary values. * MUST: Do not restyle design-system components with padding, colors, or typography via `className` — use variants/sizes, or layout/width only. * MUST: Form controls (`Input`, `Textarea`, `SelectTrigger`, `MaskInput`, `SegmentedInput`) own their padding. Call sites use layout/width only. * MUST: Never put `text-sm` / `text-xs` on editable form controls (17px floor). * MUST: Never add horizontal margin to an icon inside `Button` or `Badge`. ## What lint catches [#what-lint-catches] | Rule | Catches | | ---------------------------- | ----------------------------------------------------- | | `shadcn/no-arbitrary-values` | Values off the 13px scale | | `shadcn/no-raw-colors` | Raw palette instead of tokens | | `shadcn/no-restyle` | Restyling DS components via `className` | | `aura/no-icon-margin` | Horizontal margin on icons inside gap-owning controls | ## Execution [#execution] Install, ESLint merge, and the post-UI fix loop live in skill `verify-aura-ui`. Do not paste setup recipes into this rule. # Client Only (/docs/utils/client-only) ## Preview [#preview] <ComponentPreview name="client-only-demo" description="Renders children only after the client has mounted."> ```tsx import { ClientOnly } from "@/components/ui/ClientOnly"; export function ClientOnlyDemo() { return ( <ClientOnly fallback={<span>Waiting for the client</span>}> <span>Ready on the client</span> </ClientOnly> ) ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/client-only ``` ### Manual [#manual] <Steps> <Step> Copy and paste the ClientOnly component into your `components/ui/ClientOnly.tsx` file. ```tsx "use client"; import * as React from "react"; function ClientOnly({ children, fallback = null, }: { children: React.ReactNode; fallback?: React.ReactNode; }) { const [ready, setReady] = React.useState(false); React.useEffect(() => setReady(true), []); return ready ? children : fallback; } export { ClientOnly }; ``` </Step> </Steps> # Direction (/docs/utils/direction) ## Preview [#preview] <ComponentPreview name="direction-demo" description="Sets reading direction for a subtree and Radix primitives."> ```tsx import { Breadcrumb, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator, } from "@/components/ui/Breadcrumb"; import { DirectionProvider } from "@/components/ui/Direction"; export function DirectionDemo() { return ( <DirectionProvider dir="ltr" className="w-full"> <Breadcrumb> <BreadcrumbList> <BreadcrumbItem> <BreadcrumbLink href="#home">Home</BreadcrumbLink> </BreadcrumbItem> <BreadcrumbSeparator /> <BreadcrumbItem> <BreadcrumbPage>Direction</BreadcrumbPage> </BreadcrumbItem> </BreadcrumbList> </Breadcrumb> </DirectionProvider> ); } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/direction ``` ### Manual [#manual] <Steps> <Step> Install the following dependencies: ```bash pnpm install radix-ui ``` </Step> <Step> Copy and paste the Direction component into your `components/ui/Direction.tsx` file. ```tsx "use client"; /** * @description Sets reading direction for Radix primitives and the subtree. / import as React from "react"; import { Direction } from "radix-ui"; function DirectionProvider({ dir = "ltr", children, className, ...props }: React.ComponentProps<typeof Direction.Provider> & { className?: string; }) { return ( <Direction.Provider dir={dir} {...props}> <div dir={dir} data-slot="direction" className={className}> {children} </div> </Direction.Provider> ); } export { DirectionProvider }; ``` </Step> </Steps> ## Usage [#usage] ### Rtl [#rtl] ```tsx export const Rtl = () => { return ( <DirectionProvider dir="rtl" className="w-full"> <p className="text-gray-12">القراءة من اليمين إلى اليسار</p> </DirectionProvider> ); }; ``` # Hitbox (/docs/utils/hitbox) ## Preview [#preview] <ComponentPreview name="hitbox-demo" description="Expands the hit area around a control without changing its look."> ```tsx import { Button } from "@/components/ui/Button"; import { Hitbox } from "@/components/ui/Hitbox"; export function HitboxDemo() { return ( <Hitbox> <Button type="button" size="sm"> Add </Button> </Hitbox> ) } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/hitbox ``` ### Manual [#manual] <Steps> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the Hitbox component into your `components/ui/Hitbox.tsx` file. ```tsx "use client"; import * as React from "react"; import { cn } from "@/utils/class-names"; function Hitbox({ children }: { children: React.ReactElement<{ className?: string }> }) { return React.cloneElement(children, { className: cn( children.props.className, "relative before:absolute before:-inset-1 before:content-['']", ), }); } export { Hitbox }; ``` </Step> </Steps> # Utils (/docs/utils) ## Utils [#utils] These utilities render little or no chrome of their own. Use them to compose accessible, client-safe, and directional UI. ### [Client Only](./client-only) [#client-only] Renders children only after the client has mounted. ### [Direction](./direction) [#direction] Sets reading direction for a subtree and Radix primitives. ### [Hitbox](./hitbox) [#hitbox] Expands the hit area around a control without changing its look. ### [Pending](./pending) [#pending] Marks content as busy and shows a spinner while work is in progress. ### [Portal](./portal) [#portal] Renders children into another element. ### [Presence](./presence) [#presence] Keeps content mounted while it fades out. ### [Visually Hidden](./visually-hidden) [#visually-hidden] Hides text visually while keeping it available to assistive tech. ### [Visually Hidden Input](./visually-hidden-input) [#visually-hidden-input] A visually hidden input that mirrors a control for form submission. # Pending (/docs/utils/pending) ## Preview [#preview] <ComponentPreview name="pending-demo" description="Marks content as busy and shows a spinner while work is in progress."> ```tsx import { Pending } from "@/components/ui/Pending"; export function PendingDemo() { return <Pending pending>Saving the theme</Pending>; } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/pending ``` ### Manual [#manual] <Steps> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the Pending component into your `components/ui/Pending.tsx` file. ```tsx "use client"; import * as React from "react"; import { cn } from "@/utils/class-names"; function Pending({ className, pending = false, children, label = "Loading", }: { className?: string; pending?: boolean; children?: React.ReactNode; label?: string; }) { return ( <span aria-busy={pending || undefined} data-slot="pending" data-pending={pending ? "" : undefined} className={cn("inline-flex items-center gap-0.5", className)} > {pending ? ( <span aria-hidden className="size-1 animate-spin rounded-full border-2 border-gray-6 border-t-accent-9 motion-reduce:animate-none" /> ) : null} <span className={pending ? "text-gray-11" : undefined}>{children}</span> {pending ? <span className="sr-only">{label}</span> : null} </span> ); } export { Pending }; ``` </Step> </Steps> # Portal (/docs/utils/portal) ## Preview [#preview] <ComponentPreview name="portal-demo" description="Renders children into another element."> ```tsx import { useState } from "react"; import { Portal } from "@/components/ui/Portal"; export function PortalDemo() { const [target, setTarget] = useState<HTMLDivElement | null>(null); return ( <div className="flex flex-col gap-0.5"> <p className="m-0 text-gray-11">The line below is rendered through a portal.</p> <div ref={setTarget} className="min-h-6 rounded-sm border border-dashed border-gray-7 p-1" /> <Portal container={target}> <span>Portaled into the frame</span> </Portal> </div> ); } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/portal ``` ### Manual [#manual] <Steps> <Step> Copy and paste the Portal component into your `components/ui/Portal.tsx` file. ```tsx "use client"; import * as React from "react"; import { createPortal } from "react-dom"; function Portal({ children, container, }: { children: React.ReactNode; container?: HTMLElement | null; }) { const [target, setTarget] = React.useState<HTMLElement | null>(container ?? null); React.useEffect(() => { setTarget(container === undefined ? document.body : container); }, [container]); if (!target) return null; return createPortal(children, target); } export { Portal }; ``` </Step> </Steps> # Presence (/docs/utils/presence) ## Preview [#preview] <ComponentPreview name="presence-demo" description="Keeps content mounted while it fades out."> ```tsx import { Presence } from "@/components/ui/Presence"; export function PresenceDemo() { return ( <Presence present> <div className="rounded-sm bg-accent-3 p-1">Visible while present</div> </Presence> ) } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/presence ``` ### Manual [#manual] <Steps> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the Presence component into your `components/ui/Presence.tsx` file. ```tsx "use client"; import * as React from "react"; import { cn } from "@/utils/class-names"; function Presence({ className, present, children, }: { className?: string; present: boolean; children?: React.ReactNode; }) { const [shown, setShown] = React.useState(present); React.useEffect(() => { if (present) { setShown(true); return; } const reduced = window.matchMedia("(prefers-reduced-motion: reduce)").matches; if (reduced) setShown(false); }, [present]); if (!shown) return null; return ( <div data-slot="presence" data-present={present ? "" : undefined} className={cn( "transition duration-300 motion-reduce:transition-none", present ? "scale-100 opacity-100" : "scale-95 opacity-0", className, )} onTransitionEnd={() => { if (!present) setShown(false); }} > {children} </div> ); } export { Presence }; ``` </Step> </Steps> # Visually Hidden Input (/docs/utils/visually-hidden-input) ## Preview [#preview] <ComponentPreview name="visually-hidden-input-demo" description="A visually hidden input that mirrors a control for form submission."> ```tsx import * as React from "react" import { Button } from "@/components/ui/Button" import { VisuallyHiddenInput } from "@/components/ui/VisuallyHiddenInput" export function VisuallyHiddenInputDemo() { const [control, setControl] = React.useState<HTMLButtonElement | null>(null) const [checked, setChecked] = React.useState(false) return ( <form className="flex flex-col items-start gap-1"> <Button ref={setControl} type="button" variant="pill" aria-pressed={checked} onClick={() => setChecked((value) => !value)} > {checked ? "Notifications enabled" : "Enable notifications"} </Button> <VisuallyHiddenInput control={control} type="checkbox" name="notifications" checked={checked} /> <output className="text-sm text-gray-11"> Hidden form value: {checked ? "on" : "off"} </output> </form> ) } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/visually-hidden-input ``` ### Manual [#manual] <Steps> <Step> Copy and paste the VisuallyHiddenInput component into your `components/ui/VisuallyHiddenInput.tsx` file. ```tsx "use client"; /** * @description A visually hidden input that mirrors a control for form submission. / import as React from "react"; type InputValue = string[] | string; interface VisuallyHiddenInputProps<T = InputValue> extends Omit< React.InputHTMLAttributes<HTMLInputElement>, "value" | "checked" | "onReset" > { value?: T; checked?: boolean; control: HTMLElement | null; bubbles?: boolean; } function VisuallyHiddenInput<T = InputValue>( props: VisuallyHiddenInputProps<T>, ) { const { control, value, checked, bubbles = true, type = "hidden", style, ...inputProps } = props; const isCheckInput = React.useMemo( () => type === "checkbox" || type === "radio" || type === "switch", [type], ); const inputRef = React.useRef<HTMLInputElement>(null); const prevValueRef = React.useRef<{ value: T | boolean | undefined; previous: T | boolean | undefined; }>({ value: isCheckInput ? checked : value, previous: isCheckInput ? checked : value, }); const prevValue = React.useMemo(() => { const currentValue = isCheckInput ? checked : value; if (prevValueRef.current.value !== currentValue) { prevValueRef.current.previous = prevValueRef.current.value; prevValueRef.current.value = currentValue; } return prevValueRef.current.previous; }, [isCheckInput, value, checked]); const [controlSize, setControlSize] = React.useState<{ width?: number; height?: number; }>({}); React.useLayoutEffect(() => { if (!control) { setControlSize({}); return; } setControlSize({ width: control.offsetWidth, height: control.offsetHeight, }); if (typeof window === "undefined") return; const resizeObserver = new ResizeObserver((entries) => { if (!Array.isArray(entries) || !entries.length) return; const entry = entries[0]; if (!entry) return; let width: number; let height: number; if ("borderBoxSize" in entry) { const borderSizeEntry = entry.borderBoxSize; const borderSize = Array.isArray(borderSizeEntry) ? borderSizeEntry[0] : borderSizeEntry; width = borderSize.inlineSize; height = borderSize.blockSize; } else { width = control.offsetWidth; height = control.offsetHeight; } setControlSize({ width, height }); }); resizeObserver.observe(control, { box: "border-box" }); return () => { resizeObserver.disconnect(); }; }, [control]); React.useEffect(() => { const input = inputRef.current; if (!input) return; const inputProto = window.HTMLInputElement.prototype; const propertyKey = isCheckInput ? "checked" : "value"; const eventType = isCheckInput ? "click" : "input"; const currentValue = isCheckInput ? checked : value; const serializedCurrentValue = isCheckInput ? checked : typeof value === "object" && value !== null ? JSON.stringify(value) : value; const descriptor = Object.getOwnPropertyDescriptor(inputProto, propertyKey); const setter = descriptor?.set; if (prevValue !== currentValue && setter) { const event = new Event(eventType, { bubbles }); setter.call(input, serializedCurrentValue); input.dispatchEvent(event); } }, [prevValue, value, checked, bubbles, isCheckInput]); const composedStyle = React.useMemo<React.CSSProperties>(() => { return { ...style, ...(controlSize.width !== undefined && controlSize.height !== undefined ? controlSize : {}), border: 0, clip: "rect(0 0 0 0)", clipPath: "inset(50%)", height: "1px", margin: "-1px", overflow: "hidden", padding: 0, position: "absolute", whiteSpace: "nowrap", width: "1px", }; }, [style, controlSize]); return ( <input type={type} {...inputProps} ref={inputRef} aria-hidden={isCheckInput} tabIndex={-1} defaultChecked={isCheckInput ? checked : undefined} style={composedStyle} /> ); } export { VisuallyHiddenInput }; ``` </Step> </Steps> # Visually Hidden (/docs/utils/visually-hidden) ## Preview [#preview] <ComponentPreview name="visually-hidden-demo" description="Hides text visually while keeping it available to assistive tech."> ```tsx import { VisuallyHidden } from "@/components/ui/VisuallyHidden"; export function VisuallyHiddenDemo() { return ( <button type="button" className="rounded-sm border border-gray-7 px-1 py-0.5"> Save <VisuallyHidden> the current theme</VisuallyHidden> </button> ) } ``` </ComponentPreview> ## Installation [#installation] Make sure that `namespace` is set in your component.json file. Namespace docs: [Learn more about namespaces](/docs/namespace) ```bash pnpm dlx shadcn@latest add @aura/visually-hidden ``` ### Manual [#manual] <Steps> <Step> Copy and paste the class names utility into your `utils/class-names.ts` file. ```ts import { clsx, type ClassValue } from "clsx" import { twMerge } from "tailwind-merge" export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) } ``` </Step> <Step> Copy and paste the VisuallyHidden component into your `components/ui/VisuallyHidden.tsx` file. ```tsx "use client"; import * as React from "react"; import { cn } from "@/utils/class-names"; function VisuallyHidden({ className, ...props }: React.ComponentProps<"span">) { return <span data-slot="visually-hidden" className={cn("sr-only", className)} {...props} />; } export { VisuallyHidden }; ``` </Step> </Steps>