# Pinfold
> Hooks-first, config-driven, accessible React UI (v1.1.0). One config object in, an accessible, themed, responsive component out. React 18+, Server Components, plain JS or TypeScript.
Rules for generating Pinfold code:
- Data goes in `items` (or raw records plus `fields`); everything else is optional with good defaults.
- Client: `const Faq = useAccordion({ items }); return `. Server Component: `const Faq = defineAccordion({ items }); return `. Same import path.
- Repeated looks are presets, defined once at module scope: `const Danger = defineButton({ variant: 'soft', tone: 'danger' })`, then `` (works in loops and Server Components).
- Use the hook only for the controller: `const Save = useButton({ label: 'Save', onClick: save }); Save.setLoading(true)`.
- Precedence for every option: use-site props, then the preset, then `defaults.` in `defineConfig()`, then the provider (size, tone, dir), then the library default.
- Styles: `import '@pinfold/css/core.css'` once, then `@pinfold/css/.css` per component, in the app entry. Never import CSS from library code.
- Global defaults: `defineConfig({ theme, radius, stylePack, defaults: { : {...} } })` passed to ``.
- Customise in this order: config, then `classNames`/`styles`/`slotProps`, then `render` per slot, then parts (``), then prop getters.
- Never pass functions from a Server Component; plain data and server-rendered JSX only.
## Install
- `npx pinfold init` (or `npm i @pinfold/react @pinfold/css`)
- shadcn: `npx shadcn add @pinfold/` with `"registries": { "@pinfold": "https://pinfold.indranildev.in/r/{name}.json" }` in components.json
## Components
- [Accordion](https://pinfold.indranildev.in/docs/accordion): A vertically stacked set of headings that each reveal a section of content. Config in, accessible accordion out. Import `@pinfold/react/accordion`. Schema: `schema/accordion.json`.
- [Button](https://pinfold.indranildev.in/docs/button): An action or a link that looks like one, from one config object. Tones, async loading, icons, focusable when disabled. Import `@pinfold/react/button`. Schema: `schema/button.json`.
- [Spinner](https://pinfold.indranildev.in/docs/spinner): An indeterminate loading indicator with a status label, from one config object. Import `@pinfold/react/spinner`. Schema: `schema/spinner.json`.
- [Separator](https://pinfold.indranildev.in/docs/separator): A line between groups of content, optionally with a label ("or"): solid, dashed, dotted or fading at the ends, in three weights and three contrasts. Import `@pinfold/react/separator`. Schema: `schema/separator.json`.
- [Kbd](https://pinfold.indranildev.in/docs/kbd): A keyboard shortcut that adapts to the platform: ⌘ on Apple devices, Ctrl elsewhere, with spoken key names. Import `@pinfold/react/kbd`. Schema: `schema/kbd.json`.
- [Skeleton](https://pinfold.indranildev.in/docs/skeleton): A placeholder in the shape of content that is loading (a shape, a ready-made layout, or any layout written as data), which swaps to the real content when it arrives. Import `@pinfold/react/skeleton`. Schema: `schema/skeleton.json`.
- [Badge](https://pinfold.indranildev.in/docs/badge): A short status label, a count, a status dot, or any mix of them, in the text flow or pinned to an anchor such as an avatar or an icon button. It can also be a clickable or removable chip. Import `@pinfold/react/badge`. Schema: `schema/badge.json`.
- [Alert](https://pinfold.indranildev.in/docs/alert): A message box with a tone icon, a title, a description, action buttons and an optional dismiss button, from one config. Import `@pinfold/react/alert`. Schema: `schema/alert.json`.
- [Avatar](https://pinfold.indranildev.in/docs/avatar): A picture of a person with initials while it loads or when it fails, an optional presence dot, or a stacked group with "+N". Import `@pinfold/react/avatar`. Schema: `schema/avatar.json`.
- [Card](https://pinfold.indranildev.in/docs/card): A surface with media, a header (avatar, eyebrow, title, subtitle, action), content, a footer and action buttons; the whole card can be one link, one button, or a checkbox or radio. Import `@pinfold/react/card`. Schema: `schema/card.json`.
- [Progress](https://pinfold.indranildev.in/docs/progress): How far a task has got (a bar, a ring or a gauge; solid, striped or segmented; determinate or indeterminate), or a measurement within a range (a meter). Import `@pinfold/react/progress`. Schema: `schema/progress.json`.
- [Tooltip](https://pinfold.indranildev.in/docs/tooltip): A short hint on hover or keyboard focus. Stays while the pointer is over it, closes on Escape, flips and shifts to stay on screen. Import `@pinfold/react/tooltip`. Schema: `schema/tooltip.json`.
- [Popover](https://pinfold.indranildev.in/docs/popover): A floating panel anchored to a trigger, opened by a click, hover, focus or from code. Holds anything: a free `content` area (a node or a function of `{ close, isOpen }`), a header, a footer and actions, scrolling inside when it is too tall. Import `@pinfold/react/popover`. Schema: `schema/popover.json`.
- [Dialog](https://pinfold.indranildev.in/docs/dialog): A native modal dialog from one config: centred, full screen, or a sheet or drawer from any edge; an alert dialog with one option. Free content, header and footer, the body scrolls inside or with the page and its edges show what is hidden. Focus trap, Escape and focus return come from the browser. Import `@pinfold/react/dialog`. Schema: `schema/dialog.json`.
- [Menu](https://pinfold.indranildev.in/docs/menu): A dropdown or context menu from a list: actions, links, rows with descriptions and your own start and end content, checkbox and radio groups it manages, sections, submenus, a search field, header and footer, loading and empty states; full keyboard support and typeahead. Import `@pinfold/react/menu`. Schema: `schema/menu.json`.
- [Toast](https://pinfold.indranildev.in/docs/toast): Short messages that appear in a corner and leave by themselves: queued, paused while read, and announced to screen readers. Errors and toasts with an action stay until dismissed. Import `@pinfold/react/toast`. Schema: `schema/toast.json`.
- [Input](https://pinfold.indranildev.in/docs/input): A text field with its label, help text and error wired up: single line or multiline, with icons, a clear button and native validation. Import `@pinfold/react/input`. Schema: `schema/input.json`.
- [Checkbox](https://pinfold.indranildev.in/docs/checkbox): A native checkbox with its label and error wired up, an indeterminate state, or a group from a list. Import `@pinfold/react/checkbox`. Schema: `schema/checkbox.json`.
- [Radio group](https://pinfold.indranildev.in/docs/radio): One choice from a list: native radios in a named group, as bare rows or cards. Import `@pinfold/react/radio`. Schema: `schema/radio.json`.
- [Switch](https://pinfold.indranildev.in/docs/switch): An on/off setting that applies at once: a native checkbox with `role="switch"`, its label and error wired up. Import `@pinfold/react/switch`. Schema: `schema/switch.json`.
- [Toggle](https://pinfold.indranildev.in/docs/toggle): A button that stays pressed, or a group of them from a list: one choice (a segmented control) or several (formatting buttons). Import `@pinfold/react/toggle`. Schema: `schema/toggle.json`.
- [Toolbar](https://pinfold.indranildev.in/docs/toolbar): A row of buttons from a list: joined into one button group, or spaced as a toolbar, with one tab stop and arrow keys between them. Import `@pinfold/react/toolbar`. Schema: `schema/toolbar.json`.
- [Slider](https://pinfold.indranildev.in/docs/slider): Pick a number, or a range with two thumbs, by dragging along a track: native range inputs, with marks and a live value. Import `@pinfold/react/slider`. Schema: `schema/slider.json`.
- [Number field](https://pinfold.indranildev.in/docs/number): A number with − and + buttons: a native number input, with steps, limits, units, press-and-hold and native validation. Import `@pinfold/react/number`. Schema: `schema/number.json`.
- [One-time code](https://pinfold.indranildev.in/docs/otp): A verification code in separate boxes, typed, pasted or filled from an SMS: one native input under the boxes, so the browser and password managers fill it. Import `@pinfold/react/otp`. Schema: `schema/otp.json`.
- [Tabs](https://pinfold.indranildev.in/docs/tabs): Panels from a list, one shown at a time, picked from a row of tabs with a sliding indicator: segmented, underline, pills, soft or enclosed; above, below or beside the panel. Tabs can be links (routes), close, and be added. Import `@pinfold/react/tabs`. Schema: `schema/tabs.json`.
- [Breadcrumb](https://pinfold.indranildev.in/docs/breadcrumb): The path to the current page, from items or straight from a URL path. A crumb can open a menu of the other pages at its level; long trails collapse into a menu. Clicks go to your router. Import `@pinfold/react/breadcrumb`. Schema: `schema/breadcrumb.json`.
- [Pagination](https://pinfold.indranildev.in/docs/pagination): Move between pages of results, client or server side: numbered pages with a sliding current-page cursor, a page-size select, go to page, a "21–40 of 532" summary, a loading state, and a compact or cursor-paged form. Import `@pinfold/react/pagination`. Schema: `schema/pagination.json`.
- [Stepper](https://pinfold.indranildev.in/docs/stepper): A task in steps: the marks (done, current, error, to come) joined by a line that fills as you go, the current step's content, and Back / Next / Finish that can wait on validation. Import `@pinfold/react/stepper`. Schema: `schema/stepper.json`.
- [Select](https://pinfold.indranildev.in/docs/select): A field that opens a list to choose one value, or several as chips. Rows from strings or objects, in groups, with descriptions and icons; type ahead to jump. A native select underneath submits, resets and validates. Import `@pinfold/react/select`. Schema: `schema/select.json`.
- [Combobox](https://pinfold.indranildev.in/docs/combobox): A text field that suggests as you type: filters your rows (accents and case ignored, matches marked), or shows results you fetch with a loading row. One value, several as chips, or free text that becomes a value (a tag input). Import `@pinfold/react/combobox`. Schema: `schema/combobox.json`.
- [Tag group](https://pinfold.indranildev.in/docs/tags): Tags (chips): labels to read, filters to remove, links, or choices to pick one or several of. Each tag can have its own tone and icon; long groups fold into "+3". Import `@pinfold/react/tags`. Schema: `schema/tags.json`.
- [Command](https://pinfold.indranildev.in/docs/command): A command palette: type to find a command (by its name or keywords, matches marked), arrows to move, Enter to run. On the page, or a modal that ⌘K / Ctrl+K opens from anywhere. Commands run a handler or go to a page. Import `@pinfold/react/command`. Schema: `schema/command.json`.
- [Calendar](https://pinfold.indranildev.in/docs/calendar): A month grid to choose a day, a range (with a preview as you point) or several days; one or more months side by side. Week start and names from the locale; dates are ISO strings, the same on the server and in every time zone. Import `@pinfold/react/calendar`. Schema: `schema/calendar.json`.
- [Date picker](https://pinfold.indranildev.in/docs/datepicker): A date field: type a date in the reader's own format (day, month and year in the locale's order) or pick it from a calendar. One day or a range; ISO values; a hidden input submits them. Import `@pinfold/react/datepicker`. Schema: `schema/datepicker.json`.
- [Table](https://pinfold.indranildev.in/docs/table): A data grid from your rows or your server: typed columns (paths reach into objects); sorting by one key or several; a menu on each header that sorts, pins, hides, groups and filters by a condition or by a searchable list of the column's values, drawn as its cells draw them; a quick search; pages or a virtual body for any number of rows (a billion included); columns that resize, reorder, pin and hide; rows that reorder, resize, expand into details, sub-tables or rows of their own to any depth, and group with totals; cells, headers, rows and filters you draw; editing; CSV export and remembered layouts. Import `@pinfold/react/table`. Schema: `schema/table.json`.
- [Rating](https://pinfold.indranildev.in/docs/rating): Stars (or any symbol) to give a score, in whole or half steps, with a preview under the pointer; or a read-only score such as 4.3 out of 5. Native radios underneath. Import `@pinfold/react/rating`. Schema: `schema/rating.json`.
- [Timeline](https://pinfold.indranildev.in/docs/timeline): Events in order: an order history, an activity feed, a roadmap. Dots, icons or cards on a line that joins the markers exactly (or stops short of them, dashed, or none); vertical or horizontal, one side or alternating; content on the other side of the line; a status per event (done, current, to come, error) that colours its marker and the line; custom markers; collapsible details; ISO times shown in the locale. Import `@pinfold/react/timeline`. Schema: `schema/timeline.json`.
- [Empty](https://pinfold.indranildev.in/docs/empty): An empty state: what is missing and what to do about it, where a list, a search or a page has nothing to show yet. An icon, a heading, a line and actions. Import `@pinfold/react/empty`. Schema: `schema/empty.json`.
- [Carousel](https://pinfold.indranildev.in/docs/carousel): Slides in a row that scrolls and snaps: swipe, trackpad, arrow buttons or dots move it. One or several in view (a fraction peeks at the next), loop, and autoplay that stops on hover, focus and reduced motion, with a pause button. Import `@pinfold/react/carousel`. Schema: `schema/carousel.json`.
- [Resizable](https://pinfold.indranildev.in/docs/resizable): Panels side by side or stacked, with handles between them to drag or move with arrow keys; each panel held within its min and max; sizes kept per browser with `autoSaveId`. Import `@pinfold/react/resizable`. Schema: `schema/resizable.json`.
- [Sidebar](https://pinfold.indranildev.in/docs/sidebar): App navigation down the side: links, buttons and sections that open, under group headings, with a header and a footer. Folds into a rail of icons. The current entry follows the router; links go through its navigate. Import `@pinfold/react/sidebar`. Schema: `schema/sidebar.json`.
- [Navigation menu](https://pinfold.indranildev.in/docs/navmenu): A site's top navigation: links, and buttons that open panels of links with icons and descriptions (a mega menu) on hover or press. The disclosure pattern, so links stay links; arrow keys move between entries. Import `@pinfold/react/navmenu`. Schema: `schema/navmenu.json`.
- [Color picker](https://pinfold.indranildev.in/docs/colorpicker): Pick a colour: a saturation and brightness area, hue and opacity sliders, a text field that takes hex, rgb(), hsl() or oklch(), swatches, and the screen eyedropper where the browser has it. The value is written in the format you choose. Import `@pinfold/react/colorpicker`. Schema: `schema/colorpicker.json`.
- [Scroll area](https://pinfold.indranildev.in/docs/scrollarea): A scrolling region that shows where more content is: a fade, a shadow, a glow or a line on each edge that hides something. Follows new content like a chat, reports reaching either end, scrolls by keyboard. Import `@pinfold/react/scrollarea`. Schema: `schema/scrollarea.json`.
- [App shell](https://pinfold.indranildev.in/docs/appshell): The frame of an app: a bar on top, a sidebar, the page, an optional panel on the far side and a footer. You fill each region with anything (a Navbar, a Sidebar, Tabs, your own); the shell does the layout, keeps the bar and sidebar in view, and turns the sidebar into a drawer with a backdrop on a narrow screen. Import `@pinfold/react/appshell`. Schema: `schema/appshell.json`.
- [Navbar](https://pinfold.indranildev.in/docs/navbar): The bar across the top of an app or a site: a brand, links (with dropdowns), your own content in the middle and at the end, and actions. Links that do not fit move under "More"; on a narrow bar they all fold into a menu button. Solid, glass or a floating pill; it can shrink or hide as the page scrolls; the current link carries a marker that slides between links. Import `@pinfold/react/navbar`. Schema: `schema/navbar.json`.
- [Cursor](https://pinfold.indranildev.in/docs/cursor): A pointer of your own design, for a whole page or one area: a dot, a ring that trails it, a blob, a spotlight, a crosshair or a named arrow, in any tone, with a trail, a label, and states for links, text, pressing and anything you mark with `data-cursor`. Decorative only: it never replaces the real pointer for touch, for reduced motion it stops trailing, and the native cursor returns the moment it unmounts. Import `@pinfold/react/cursor`. Schema: `schema/cursor.json`.
- [Tree view](https://pinfold.indranildev.in/docs/treeview): Nested data you can open, select, check, search and reorder: files and folders, categories, an org chart. The WAI-ARIA tree pattern with full keyboard support and typeahead; single or multiple selection, or tri-state checkboxes where a parent reflects its children; children loaded on demand with a loading and an error row; a search that keeps the path to every match; indent guides; drag by a handle or Alt + arrows to reorder. Import `@pinfold/react/treeview`. Schema: `schema/treeview.json`.
- [File upload](https://pinfold.indranildev.in/docs/fileupload): Pick or drop files: a drop zone, a button or a compact row that opens the file dialog from the keyboard too. Rules for type, size and count with every rejected file listed and why; image previews; a list with progress per file when you give it an `upload` function (aborted on remove, retried on error); paste to add; a hidden input with a `name` for native forms. File contents are never read except to show an image preview. Import `@pinfold/react/fileupload`. Schema: `schema/fileupload.json`.
- [Tour](https://pinfold.indranildev.in/docs/tour): A guided walk over the real interface: a spotlight cuts a rounded hole in a dimmed (or blurred) page around each target and glides from one to the next, while a card beside it explains the step. Next, Back and Skip, a step counter and progress dots, arrow keys, Escape to skip; it scrolls each target into view and follows it through scrolling and resizing; a guard can hold a step; a step without a target, or whose target is missing, sits in the middle. Import `@pinfold/react/tour`. Schema: `schema/tour.json`.
## Reference
- [Full reference](https://pinfold.indranildev.in/llms-full.txt): every option of every component (also `llms-full.txt` in this package)
- [Theming](https://pinfold.indranildev.in/docs/theming): `npx pinfold theme`, style packs (glass, material, noise, brutalist), DTCG tokens
- Local MCP server: `npx pinfold mcp` (tools: search_components, list_components, get_component, get_schema, validate_config, get_install_steps)