# frappe-ui

> Vue 3 component library and data-fetching utilities for building UIs on the Frappe Framework. Used by Frappe Cloud, Gameplan, Desk, Drive, and Insights. Components ship with TypeScript, dark mode via `[data-theme="dark"]`, and a semantic Tailwind preset (`ink-*` / `surface-*` / `outline-*` tokens).

Built on Vue 3, TailwindCSS, Headless UI, reka-ui, TipTap, and lucide icons. Distributed as the `frappe-ui` npm package; import everything from `'frappe-ui'`.

Two cross-cutting conventions to know before reading anything else:

- **Color = `variant` + `theme`.** `variant` is visual style (`solid | outline | subtle | ghost`); `theme` is color tone (`gray | blue | red | green | …`). No `intent` / `severity` / `appearance` axis.
- **Icons are CSS classes.** Render as `<span class="lucide-<name> size-4" aria-hidden="true" />`. Frappe-ui props that accept icons take the namespaced string `"lucide-edit"`.

## Design principles

- [PHILOSOPHY.md](https://raw.githubusercontent.com/frappe/frappe-ui/main/PHILOSOPHY.md): the 13 rules (P1–P13) that govern API shape across the library — naming, prop design, slots, composition, styling, a11y, deprecation policy.
- [CONTEXT.md](https://raw.githubusercontent.com/frappe/frappe-ui/main/CONTEXT.md): canonical vocabulary (`open`, `variant`, `theme`, `dismissible`, `bare`, `chrome`, `action`, …). Reference for prop and slot names.

## Getting started

- [Introduction](https://ui.frappe.io/docs/introduction): what frappe-ui is, motivation, products using it.
- [Getting started](https://ui.frappe.io/docs/getting-started): installation, Tailwind preset wiring, `FrappeUIProvider` setup.

## Core components

- [Alert](https://ui.frappe.io/docs/components/alert): inline status row or banner; title, description, theme-colored status icon, primary/secondary actions, dismiss.
- [Avatar](https://ui.frappe.io/docs/components/avatar): user/entity avatar with image or label-derived initials.
- [Badge](https://ui.frappe.io/docs/components/badge): status pill; same `variant` + `theme` axes as Button.
- [Breadcrumbs](https://ui.frappe.io/docs/components/breadcrumbs): page-header trail; takes `items: { label, route }[]`.
- [Button](https://ui.frappe.io/docs/components/button): primary trigger element; supports `route`/`link` for nav, `icon`/`iconLeft`/`iconRight`, `loading`, `disabled`.
- [Charts](https://ui.frappe.io/docs/charts/overview): chart family (line, bar, etc.); one page per chart under `/docs/charts`.
- [Checkbox](https://ui.frappe.io/docs/components/checkbox): boolean input; standard labeling contract.
- [Combobox](https://ui.frappe.io/docs/components/combobox): single-select with search; `v-model` value + `v-model:query`.
- [DatePicker](https://ui.frappe.io/docs/components/datepicker): date input; also DateRangePicker (range is `string[]`).
- [Dialog](https://ui.frappe.io/docs/components/dialog): modal overlay; `v-model:open`, `title`/`message`/`icon`/`theme`/`actions`/`dismissible`/`bare`. Imperative API: `dialog.confirm`, `dialog.alert`, `dialog.prompt`.
- [Divider](https://ui.frappe.io/docs/components/divider): horizontal/vertical rule.
- [Dropdown](https://ui.frappe.io/docs/components/dropdown): action menu anchored to a trigger; takes `options` (flat or grouped).
- [Editor](https://ui.frappe.io/docs/molecules/editor): TipTap-based rich editor, from the `frappe-ui/editor` subpath (heavy, and not SSR-safe — use only when needed).
- [ErrorMessage](https://ui.frappe.io/docs/components/errormessage): inline error display.
- [FileUploader](https://ui.frappe.io/docs/components/fileuploader): Frappe-native file upload with progress.
- [FormControl](https://ui.frappe.io/docs/components/formcontrol): the default labeled-field wrapper; pick `type` to render text/textarea/select/checkbox/combobox with the shared `label`/`description`/`error`/`required` contract.
- [ItemListRow](https://ui.frappe.io/docs/components/itemlistrow): single-row list item primitive.
- [List](https://ui.frappe.io/docs/molecules/list): the list primitive, from the `frappe-ui/list` subpath; `List` + `ListRow`/`ListCell`, feed or table mode.
- [MultiSelect](https://ui.frappe.io/docs/components/multiselect): multi-value select; value is `string[]`.
- [Password](https://ui.frappe.io/docs/components/password): masked input with show/hide.
- [Popover](https://ui.frappe.io/docs/components/popover): anchored floating panel; `v-model:open`, `#target` + `#body` slots.
- [Progress](https://ui.frappe.io/docs/components/progress): linear progress bar.
- [Rating](https://ui.frappe.io/docs/components/rating): star-rating input.
- [Select](https://ui.frappe.io/docs/components/select): fixed-options single-value select.
- [Sidebar](https://ui.frappe.io/docs/components/sidebar): app-shell sidebar primitive.
- [Slider](https://ui.frappe.io/docs/components/slider): numeric range input.
- [Switch](https://ui.frappe.io/docs/components/switch): boolean toggle for settings.
- [Tabs](https://ui.frappe.io/docs/components/tabs): full content tabs and inline TabButtons.
- [Textarea](https://ui.frappe.io/docs/components/textarea): multi-line text input.
- [TextInput](https://ui.frappe.io/docs/components/textinput): single-line text input.
- [TimePicker](https://ui.frappe.io/docs/components/timepicker): time input.
- [Toast](https://ui.frappe.io/docs/components/toast): imperative notifications: `toast.success/error/info`.
- [Tooltip](https://ui.frappe.io/docs/components/tooltip): hover hint; not for actionable content (use Popover/Dropdown).
- [Tree](https://ui.frappe.io/docs/components/tree): hierarchical list.

## Foundations

- [Tailwind setup](https://ui.frappe.io/docs/foundations/tailwind): wiring the preset into an app.
- [Base colors](https://ui.frappe.io/docs/foundations/colors/base): the raw color scales.
- [Semantic colors](https://ui.frappe.io/docs/foundations/colors/semantic): `bg-surface-*`, `text-ink-*`, `border-outline-*` tokens.
- [Chart colors](https://ui.frappe.io/docs/foundations/colors/charts): the categorical chart palette.
- [Typography](https://ui.frappe.io/docs/foundations/typography): the type scale.
- [Radius](https://ui.frappe.io/docs/foundations/radius): radius scale.
- [Elevation](https://ui.frappe.io/docs/foundations/elevation): shadow scale.
- [Focus ring](https://ui.frappe.io/docs/foundations/focus-ring): the shared focus treatment.

## Experimental and legacy

- [Experimental](https://ui.frappe.io/docs/experimental): everything on the `frappe-ui/experimental` subpath — parked v0 families (`Calendar`, `ListView`, v1 charts, v0 `TextEditor`, sprite icons) and incubating exports. Unstable: no deprecation promise. Do not import it from product apps.
- [Legacy components](https://ui.frappe.io/docs/components/legacy): what was removed in v1 and the replacement for each, plus which families were parked rather than removed.

## Data fetching

Recommended layer for new code, in the `frappe-ui` exports:

- [useCall](https://ui.frappe.io/docs/data-fetching/use-call): Vue composable for any whitelisted Frappe method. Options: `url`, `method`, `params` (object or function for reactivity), `immediate`, `refetch`, `cacheKey` (IndexedDB persistence), `transform`, `beforeSubmit`, `onSuccess`, `onError`. Returns a reactive object with `data`, `error`, `loading`, `isFinished`, `promise`, `execute`/`fetch`/`reload`, `submit(params)`, `reset`, `abort`. Use `immediate: false` + `submit()` for writes.
- [useDoc](https://ui.frappe.io/docs/data-fetching/use-doc): fetches and keeps one document reactive, shared with `useList` for the same `doctype`/`name`.
- [useList](https://ui.frappe.io/docs/data-fetching/use-list): paginated, filterable list for a doctype, with `insert`/`setValue`/`delete` write helpers.
- [useDoctype](https://ui.frappe.io/docs/data-fetching/use-doctype): write-only helpers for a doctype — `insert`, `delete`, `setValue`, `runDocMethod`, `runMethod` — with no read/fetch of its own.
- [useNewDoc](https://ui.frappe.io/docs/data-fetching/use-new-doc): a reactive draft for a new document, submitted as an insert.

## Resources

Fully supported through `1.x`; use Data Fetching above for new code.

- [Resource](https://ui.frappe.io/docs/data-fetching/resource): `createResource` — base data fetcher.
- [List resource](https://ui.frappe.io/docs/data-fetching/list-resource): `createListResource` — paginated list.
- [Document resource](https://ui.frappe.io/docs/data-fetching/document-resource): `createDocumentResource` — single doc.

## Other

- [Icons](https://ui.frappe.io/docs/other/icons): the lucide icon-class system; how `<span class="lucide-* size-*" aria-hidden="true" />` works.
- [Directives](https://ui.frappe.io/docs/other/directives): Vue directives shipped with frappe-ui.
- [Utilities](https://ui.frappe.io/docs/other/utilities): helper functions exported from the package.

## Optional

- [v1-release plan](https://github.com/frappe/frappe-ui/tree/main/v1-release): API-freeze plan, component specs, ADRs. Read when contributing to frappe-ui itself or making decisions about API direction.
- [GitHub repository](https://github.com/frappe/frappe-ui): source, issues, releases.
- [Changelog](https://ui.frappe.io/docs/changelog): notable changes per release.