# PersianLabs UI

> An open-source, RTL-first component library for Persian interfaces. Beautifully-designed components built on Base UI primitives, TypeScript, and Tailwind CSS - distributed as source through a shadcn-compatible registry, so there's no package to install and no version to chase. Every doc page is available as markdown by appending .md to its URL.

## Overview

- [Introduction](https://ui.persian-labs.ir/docs): What PersianLabs UI is, and why there's no separate installation flow - it's built entirely on top of shadcn/ui.

- [Theming](https://ui.persian-labs.ir/docs/theming): The CSS color variables the library ships with, light and dark, ready to copy.

- [Charts](https://ui.persian-labs.ir/docs/charts): Chart components - pointers to dedicated collections.

## Components

### Form & Input

- [Bank Input](https://ui.persian-labs.ir/docs/components/bank-input): Iranian card-number and Shaba inputs with formatting, checksum validation, and bank detection.
- [Button](https://ui.persian-labs.ir/docs/components/button): A button built on Base UI with variant and size support.
- [Checkbox](https://ui.persian-labs.ir/docs/components/checkbox): A control for selecting one or more options, built on Base UI.
- [City Selector](https://ui.persian-labs.ir/docs/components/city-selector): A province and city picker for Iran, built on Combobox and bundled with a full dataset of all 31 provinces and 1,119 cities.
- [Combobox](https://ui.persian-labs.ir/docs/components/combobox): A searchable, accessible combobox built on Base UI.
- [Date Picker](https://ui.persian-labs.ir/docs/components/date-picker): An opinionated, responsive Shamsi/Gregorian date and date-time picker with SSR-safe defaults and accessible confirmation flows.
- [Date Wheel Picker](https://ui.persian-labs.ir/docs/components/date-wheel-picker): An iOS-style year/month/day wheel-based date picker, switchable between the Shamsi and Gregorian calendars, with a responsive Popover-on-desktop, Drawer-on-mobile composition.
- [Elastic Range Slider](https://ui.persian-labs.ir/docs/components/elastic-range-slider): A single-track, dual-thumb range slider in the same visual language as Elastic Slider.
- [Elastic Slider](https://ui.persian-labs.ir/docs/components/elastic-slider): Slider with elastic rubber-band drag and magnetic snap feedback.
- [Field](https://ui.persian-labs.ir/docs/components/field): Groups a label, control, and description into an accessible form field, built on Base UI.
- [Input](https://ui.persian-labs.ir/docs/components/input): A styled text input built on Base UI.
- [Input Group](https://ui.persian-labs.ir/docs/components/input-group): Add addons, buttons, and helper content to inputs.
- [Input OTP](https://ui.persian-labs.ir/docs/components/input-otp): Accessible one-time password component with copy-paste functionality.
- [Label](https://ui.persian-labs.ir/docs/components/label): An accessible, styled label element.
- [Mobile Number Input](https://ui.persian-labs.ir/docs/components/mobile-number-input): An Iranian mobile number input that normalizes mixed paste formats and Persian digits, with a redundant validity indicator.
- [Native Select](https://ui.persian-labs.ir/docs/components/native-select): A styled native <select> element for choosing a single value.
- [Password Input](https://ui.persian-labs.ir/docs/components/password-input): A password input with a show/hide toggle that always renders LTR, regardless of the surrounding document direction.
- [Plate Input](https://ui.persian-labs.ir/docs/components/plate-input): An Iranian vehicle license plate input with digit segments, a letter picker including wheelchair plates, and the Iran serial tab.
- [Price Input](https://ui.persian-labs.ir/docs/components/price-input): A text input that live-formats digits as a grouped price as you type, with support for Persian/Arabic-Indic numerals.
- [Questionnaire](https://ui.persian-labs.ir/docs/components/questionnaire): A multi-step questionnaire with single-choice, multiple-choice, freeform, and skippable questions, built on @shadcn/react.
- [Radio Group](https://ui.persian-labs.ir/docs/components/radio-group): A set of mutually exclusive radio buttons, built on Base UI.
- [Select](https://ui.persian-labs.ir/docs/components/select): A listbox for choosing a single value, built on Base UI.
- [Slider](https://ui.persian-labs.ir/docs/components/slider): An input where the user selects a value from within a given range, built on Base UI.
- [Switch](https://ui.persian-labs.ir/docs/components/switch): A control that toggles between checked and unchecked, built on Base UI.
- [Textarea](https://ui.persian-labs.ir/docs/components/textarea): Displays a form textarea or a component that looks like a textarea.
- [Time Picker](https://ui.persian-labs.ir/docs/components/time-picker): An hour/minute/second wheel-based time picker, with a responsive Popover-on-desktop, Drawer-on-mobile composition.
- [Wheel Picker](https://ui.persian-labs.ir/docs/components/wheel-picker): An iOS-like wheel picker with smooth inertia, infinite scrolling, and keyboard navigation.

### Layout & Navigation

- [Accordion](https://ui.persian-labs.ir/docs/components/accordion): A vertically stacked set of interactive headings that each reveal a section of content, built on Base UI.
- [Breadcrumb](https://ui.persian-labs.ir/docs/components/breadcrumb): Displays the path to the current resource using a hierarchy of links.
- [Item](https://ui.persian-labs.ir/docs/components/item): A flexible layout for a piece of content, media, or action, often used in lists.
- [Navigation Menu](https://ui.persian-labs.ir/docs/components/navigation-menu): A collection of links for navigating websites.
- [Resizable](https://ui.persian-labs.ir/docs/components/resizable): Accessible resizable panel groups and layouts, built on react-resizable-panels.
- [Scroll Area](https://ui.persian-labs.ir/docs/components/scroll-area): Cross-browser custom scrollbars, built on Base UI.
- [Separator](https://ui.persian-labs.ir/docs/components/separator): Visually or semantically separates content, built on Base UI.
- [Sidebar](https://ui.persian-labs.ir/docs/components/sidebar): A composable, collapsible application sidebar with mobile drawer, tooltips, and RTL support. Built on Base UI.
- [Tabs](https://ui.persian-labs.ir/docs/components/tabs): An accessible, animated tabs component with a spring-driven sliding indicator, built on Base UI and Motion.

### Overlays & Dialogs

- [Alert Dialog](https://ui.persian-labs.ir/docs/components/alert-dialog): A modal dialog that interrupts the user with important content and expects a response, built on Base UI.
- [Command](https://ui.persian-labs.ir/docs/components/command): A command palette component built with Dialog and Autocomplete for searching and executing commands.
- [Context Menu](https://ui.persian-labs.ir/docs/components/context-menu): A menu of actions triggered by a right click, built on Base UI.
- [Dialog](https://ui.persian-labs.ir/docs/components/dialog): A modal window layered over the page for focused tasks or confirmations, built on Base UI.
- [Drawer](https://ui.persian-labs.ir/docs/components/drawer): A swipeable panel that slides in from an edge of the screen, built on Base UI.
- [Dropdown Menu](https://ui.persian-labs.ir/docs/components/dropdown-menu): Displays a menu of actions or options, triggered by a button.
- [Hover Card](https://ui.persian-labs.ir/docs/components/hover-card): For sighted users to preview content available behind a link, built on Base UI.
- [Menubar](https://ui.persian-labs.ir/docs/components/menubar): A persistent horizontal menu bar for application-style commands, built on Base UI.
- [Popover](https://ui.persian-labs.ir/docs/components/popover): Displays rich content in a portal, anchored to a trigger.
- [Responsive Alert Dialog](https://ui.persian-labs.ir/docs/components/responsive-alert-dialog): Renders an Alert Dialog on desktop and a bottom Drawer on mobile from one shared set of components.
- [Responsive Dialog](https://ui.persian-labs.ir/docs/components/responsive-dialog): Renders a Dialog on desktop and a bottom Drawer on mobile from one shared set of components.
- [Responsive Menu](https://ui.persian-labs.ir/docs/components/responsive-menu): Renders a Dropdown Menu on desktop and a bottom Drawer menu on mobile from one shared set of components.
- [Sheet](https://ui.persian-labs.ir/docs/components/sheet): A panel that slides in from an edge of the screen to complement the main content, built on Base UI.
- [Tooltip](https://ui.persian-labs.ir/docs/components/tooltip): Displays contextual information when hovering or focusing an element, built on Base UI.

### Feedback & Status

- [Alert](https://ui.persian-labs.ir/docs/components/alert): Displays a callout for important, contextual messages.
- [Badge](https://ui.persian-labs.ir/docs/components/badge): Displays a small badge to highlight status or metadata.
- [Copy Button](https://ui.persian-labs.ir/docs/components/copy-button): An icon button that copies text to the clipboard, morphs its icon to reflect the result, and anchors a confirmation toast to itself.
- [Empty](https://ui.persian-labs.ir/docs/components/empty): Displays an empty state with a title, description, and optional actions.
- [Progress](https://ui.persian-labs.ir/docs/components/progress): Displays an indicator showing the completion progress of a task, built on Base UI.
- [Skeleton](https://ui.persian-labs.ir/docs/components/skeleton): Used to show a placeholder while content is loading.
- [Spinner](https://ui.persian-labs.ir/docs/components/spinner): A spinning loading indicator icon.
- [Status Button](https://ui.persian-labs.ir/docs/components/status-button): A button that swaps between idle, loading, and success feedback for async actions.
- [Toast](https://ui.persian-labs.ir/docs/components/toast): A temporary notification that stacks in a corner of the screen or anchors to an element, built on Base UI.

### Display & Media

- [Aspect Ratio](https://ui.persian-labs.ir/docs/components/aspect-ratio): Displays content within a desired ratio.
- [Attachment](https://ui.persian-labs.ir/docs/components/attachment): Displays a file or image attachment with media, metadata, upload state, and actions.
- [Avatar](https://ui.persian-labs.ir/docs/components/avatar): An image element with a fallback, for representing a user or entity, built on Base UI.
- [Card](https://ui.persian-labs.ir/docs/components/card): Displays a card with header, content, and footer.
- [Carousel](https://ui.persian-labs.ir/docs/components/carousel): A carousel with motion and swipe built using Embla.
- [Data Table](https://ui.persian-labs.ir/docs/components/data-table): Powerful table and datagrids built using TanStack Table on top of the Table component.
- [Kbd](https://ui.persian-labs.ir/docs/components/kbd): Displays a keyboard key or shortcut.
- [Marker](https://ui.persian-labs.ir/docs/components/marker): A small label for annotating content, such as a section divider or inline note.
- [QR Code](https://ui.persian-labs.ir/docs/components/qr-code): QR code generator with rounded finder patterns and dot-style data modules.
- [Receipt Printer](https://ui.persian-labs.ir/docs/components/receipt-printer): A tactile checkout experience that turns payment processing into a printed receipt.
- [Table](https://ui.persian-labs.ir/docs/components/table): A responsive table component, with an optional card-row variant.
- [Toman Icon](https://ui.persian-labs.ir/docs/components/toman-icon): The Toman currency symbol, as a standalone icon component.
- [Typography](https://ui.persian-labs.ir/docs/components/typography): Styles for headings, paragraphs, lists, etc.

### Chat

- [Bubble](https://ui.persian-labs.ir/docs/components/bubble): A chat message bubble with variants, reactions, and start/end alignment.
- [Message](https://ui.persian-labs.ir/docs/components/message): Composable layout for a chat message with an avatar, header, content, and footer.
- [Message Scroller](https://ui.persian-labs.ir/docs/components/message-scroller): An auto-scrolling viewport for chat messages, with scroll-to-start/end buttons, built on @shadcn/react.

### Misc

- [Button Group](https://ui.persian-labs.ir/docs/components/button-group): A container that groups related buttons together with consistent styling.
- [Collapsible](https://ui.persian-labs.ir/docs/components/collapsible): An interactive component which expands/collapses a panel, built on Base UI.
- [Direction](https://ui.persian-labs.ir/docs/components/direction): A provider for setting the reading direction (LTR or RTL) of your app, built on Base UI.
- [Pagination](https://ui.persian-labs.ir/docs/components/pagination): Navigation for paginated content, built on Button.
- [Toggle](https://ui.persian-labs.ir/docs/components/toggle): A two-state button that can be either on or off, built on Base UI.
- [Toggle Group](https://ui.persian-labs.ir/docs/components/toggle-group): A set of two-state buttons that can be toggled on or off, built on Base UI.

## Utilities

### Libraries

- [Hitbox](https://ui.persian-labs.ir/docs/utilities/hitbox): Extends the clickable area of a child element for improved accessibility.
- [Iranian Bank](https://ui.persian-labs.ir/docs/utilities/iranian-bank): Card and Shaba normalization, validation, and Iranian bank detection.
- [National ID](https://ui.persian-labs.ir/docs/utilities/national-id): Validates Iranian national ID (کد ملی) numbers using the standard checksum and known issuance-office prefixes.
- [Normalize Persian Digits](https://ui.persian-labs.ir/docs/utilities/normalize-persian-digits): Converts Persian (۰-۹) and Arabic-Indic (٠-٩) numerals to plain 0-9 digits.
- [Persian Date](https://ui.persian-labs.ir/docs/utilities/persian-date): Jalali/Gregorian date utilities built on date-fns and date-fns-jalali: formatting, parsing, conversion, ranges, and digit conversion, switchable with a calendarType prop.
- [Persian Date (Zod)](https://ui.persian-labs.ir/docs/utilities/persian-date-zod): zod schemas for persian-date: coerce and validate a date, or a from/to reservation-style range.
- [Persian Holidays](https://ui.persian-labs.ir/docs/utilities/persian-holidays): Official/religious/cultural Iranian holiday lookup for a date, range, or year, resolving Jalali, Gregorian, and tabular-Hijri entries.
- [Persian Reshape](https://ui.persian-labs.ir/docs/utilities/persian-reshape): Pre-shapes Persian/Arabic text for Satori/next-og images, which don't shape connected scripts on their own.
- [Persian Slug](https://ui.persian-labs.ir/docs/utilities/persian-slug): Converts Persian/mixed Persian+English text into a URL-safe slug, keeping Persian script by default or transliterating to Latin/ASCII.
- [Postal Code](https://ui.persian-labs.ir/docs/utilities/postal-code): Validates the structural format of Iranian postal codes (کد پستی).

### Hooks

- [useControllableState](https://ui.persian-labs.ir/docs/utilities/use-controllable-state): A hook for a value that can be either controlled or uncontrolled, with a single consistent API either way.
- [useCopyToClipboard](https://ui.persian-labs.ir/docs/utilities/use-copy-to-clipboard): A React hook that wraps the Clipboard API with a built-in timeout to reset the copied state.
- [useCountdown](https://ui.persian-labs.ir/docs/utilities/use-countdown): A timer-aligned React countdown hook for ISO-8601 target dates, with formatted output and overdue state.
- [useDate](https://ui.persian-labs.ir/docs/utilities/use-date): A reactive current date/time hook with Jalali/Gregorian support, formatted output, and optional holiday flagging.
- [useMediaQuery](https://ui.persian-labs.ir/docs/utilities/use-media-query): Reactive media query hook with Tailwind-like syntax.
- [useTimeAgo](https://ui.persian-labs.ir/docs/utilities/use-time-ago): A reactive relative-time formatter ("۲ روز پیش" / "2 days ago") with built-in Persian and English message tables.

## Registry

- Install a component: `npx shadcn@latest add @persianlabsui/<name>`
- Direct URL form: `npx shadcn@latest add https://ui.persian-labs.ir/r/<name>.json`
- Registry item JSON: https://ui.persian-labs.ir/r/<name>.json
- Agent guide: https://github.com/persianlabs/ui/tree/main/docs/agents
- Contributing guide: https://github.com/persianlabs/ui/tree/main/docs/contributing
- Source: https://github.com/persianlabs/ui