Migration from v0 ​

A guide for moving an existing app onto frappe-ui v1. Work through one component family at a time. Each section opens with a before/after table. For the full change list see the changelog; for the rationale behind each API see the v1 release specs.

After each pass, grep for the old prop or slot name to catch anything missed, then test the flows you touched. Type-checking won't catch focus, slot renames, or visual regressions.

What this guide covers ​

Every silent break has a before/after here: old code that still runs, still type-checks, and behaves differently. Vue drops an unknown prop or slot without a word, so those are the ones that reach production. Each is marked.

Loud breaks — an import that stops resolving, a type that no longer exists — are listed in the changelog and only appear here when the replacement needs explaining. If your build already names the file and the line, the changelog is the faster read.

Run the codemod linked from each relevant section. The tools cover Tailwind token renames (tokens-v2, see Tokens), shortcut config (shortcuts-v1, see The shortcuts codemod), destination prop renames (destinations-v1, see Destinations), overlay and picker controls (overlays-v1), navigation props and tab state (navigation-v1), and the EditorFixedMenu prop rename (editor-v1, see Editor), base component prop normalization (base-props-v1, see Base component props), and List row hooks and slot names (list-v1, see List family), and the FrappeUI plugin's resources option (data-v1, see the plugin), and the Tailwind preset path plus the Vite plugin's lucideIcons option (packaging-v1, see Packaging and tokens). The tools report ambiguous dynamic syntax for manual review instead of guessing.

Sections ​

• Overlays — Dialog · Popover / HoverCard / Tooltip · CommandPalette
• Pickers and selection — DatePicker / TimePicker · MonthPicker · Selection family · Autocomplete · FormControl type="autocomplete"
• Inputs and files — Inputs · FileUploader
• Navigation and layout — Destinations · Sidebar · Tabs · TabButtons · PageHeaderMobile · Divider
• Keyboard — useShortcut · KeyboardShortcutsModal · The shortcuts codemod · KeyboardShortcut
• Display — Alert · Icons · Base component props · List family · Tree · Card, ListItem, Toast
• Editor and charts — Editor · Code editor · Charts
• Data and transport — useDoctype / useList · Writes reject · Data-fetching exports · HTTP transport and the plugin · beforeSubmit · Errors renamed · Composables and directives · pageMetaPlugin
• Packaging — Preset path · lucideIcons · Focus ring · Sizing changes · Dependencies
• Tokens and CSS — Tokens · Line height · Family stylesheets · hljs-theme.css and tailwind/tokens.js
• Moved, not removed — these five families changed an import path and nothing else: ListView · Calendar · Charts (v1) · Sprite icons · ThemeSwitcher, which stays deprecated at its new path. The v0 TextEditor family moved the same way — see Editor.
• Removed subpaths — frappe-ui/frappe and frappe-ui/drive

Requirements ​

v1 requires Node >=20.19.0 (package.json engines). The 0.1.x line declared no engines field at all, so this is a new floor rather than a raised one — a Node 18 image that built v0 fine now fails to install.

Vue and vue-router are unchanged: vue >=3.5.0 and vue-router ^4.1.6 (package.json peerDependencies). An app already on v0 needs no Vue bump.

Tailwind stays on v3. frappe-ui/tailwind is a v3 preset and frappe-ui declares no tailwindcss peer dependency, so a v4 project installs cleanly and then fails at build time. See the Tailwind page.

v1 also depends on @vueuse/core ^14.1.0, up from ^10.4.1 in the 0.1.x line. VueUse 14 requires Vue ^3.5.0, which v1 already requires. If your app depends on @vueuse/core directly, move it to ^14 as well. Two major ranges in one app install two copies of the library, and a resolve.dedupe entry for @vueuse/core then collapses them onto whichever copy wins. That breaks the components which expect the newer one.

Navigation destinations ​

Run npx destinations-v1 . to migrate statically named component props imported from frappe-ui. It covers the first three renames below, including bound and shorthand props:

• Replace component router props named to with route. Keep to only inside the route object itself.
• Replace Button link with href for external URLs.
• Replace PageHeader back to with fallbackRoute.
• Replace TabButton tooltip with app-owned help UI and convert non-string labels to strings.

The codemod deliberately leaves globally registered components, JavaScript and TypeScript data objects, render functions, and v-bind="object" spreads alone. Review those shapes by hand.

Dialog ​

The options blob is flattened into top-level props. See the Dialog component page for the full API.

Most of this table is silent: Vue drops an unknown prop or slot with no error, so the dialog renders with no title, no actions, or an empty body, and a leftover :disable-outside-click-to-close quietly becomes dismissible. Two rows are loud instead — onClick: (close) => close() throws TypeError: close is not a function, and a template-ref .close() throws the same way. v-model itself still works (modelValue is kept as a second binding), but open is canonical and wins when both are bound.

<!-- Before -->
<Dialog :options="{ title: 'Edit Item' }" v-model="show">
  <template #body-content>
    <FormControl label="Name" v-model="item.name" />
  </template>
  <template #actions>
    <Button variant="solid" @click="save">Save</Button>
  </template>
</Dialog>

<!-- After -->
<Dialog title="Edit Item" v-model:open="show">
  <FormControl label="Name" v-model="item.name" />
  <template #actions>
    <Button variant="solid" @click="save">Save</Button>
  </template>
</Dialog>

For reactive :options objects, spread them: <Dialog v-bind="opts || {}" />. For the imperative API, use dialog.confirm / dialog.danger / dialog.prompt from frappe-ui (callback-based: onConfirm resolves to close, throws to stay open) and wrap your app root in <FrappeUIProvider>.

The icon object is replaced by icon + theme ​

icon takes a lucide-* class name or a Vue component. The tone moves to its own theme prop, so the two decisions are separate and an icon component is possible at all.

<!-- Before -->
<Dialog :icon="{ name: 'lucide-alert-triangle', theme: 'red' }" ... />

<!-- After -->
<Dialog icon="lucide-alert-triangle" theme="red" ... />
<Dialog :icon="AlertTriangleIcon" theme="red" ... />

The same two keys move on dialog.confirm, dialog.danger and dialog.prompt, which already had a top-level theme:

// Before
dialog.confirm({
  title: 'Delete',
  icon: { name: 'lucide-trash', theme: 'red' },
})

// After
dialog.confirm({ title: 'Delete', icon: 'lucide-trash', theme: 'red' })

Loud in dev, silent in production. An object passed to icon now renders an empty icon badge: the circle paints in the neutral tone with no glyph in it. A development build warns once per component and prop:

[frappe-ui] Dialog.icon received a plain object (keys: name, theme). The
{ name, theme } icon object was removed in 1.0.0. Pass a lucide-* string or a
component, and set `theme` at the top level. The icon renders empty.

The theme inside the old object is ignored, so pass theme at the top level. The DialogIcon type is gone (loud in TypeScript). Coming from v0, the older appearance key went the same way: map warning → amber, info → blue, danger → red, success → green and pass it as theme.

DialogAction is ImperativeDialogAction for dialog.* ​

Two action types existed under one name. The component's actions prop takes DialogAction, whose onClick receives { close }. The imperative helpers take a different shape, whose onClick receives { close, setError } and is awaited. That one is exported as ImperativeDialogAction.

// Before: the name resolved to the component's type, which does not match
import type { DialogAction } from 'frappe-ui'
const actions: DialogAction[] = [{ label: 'Delete', onClick: async () => {} }]
dialog.confirm({ title: 'Delete', actions })

// After
import type { ImperativeDialogAction } from 'frappe-ui'
const actions: ImperativeDialogAction[] = [
  { label: 'Delete', onClick: async () => {} },
]

Types only; nothing changes at runtime.

theme: 'yellow' → theme: 'amber' ​

The warning tone is amber, matching Alert, SidebarCard, Badge and Avatar. Dialog was the last component spelling it yellow, and it already rendered that value with the amber tokens — only the word changes, not the color.

This is a silent break for JavaScript call sites: yellow is no longer a key in the tone maps, so the icon renders with no tone and nothing throws. TypeScript call sites get a union error.

A template ref no longer exposes close() ​

<!-- Before -->
<Dialog ref="dialogRef" v-model="show" />
<script setup>
dialogRef.value.close()
</script>

<!-- After -->
<Dialog v-model:open="show" />
<script setup>
show.value = false
</script>

Dialog exposes nothing on its template ref (ADR-0012); calling .close() now throws. Drive open through v-model:open, or use the close slot prop from inside #default / #actions.

DatePicker / TimePicker family ​

Covers DatePicker, DateRangePicker, DateTimePicker, and TimePicker. They share the popover-trigger vocabulary. Every removed prop and slot below is deleted, not aliased — and nothing warns at the tag: an unknown prop lands as an inert attribute, a renamed slot stops rendering. grep for each old name after upgrading.

@change still fires alongside @update:modelValue — it wasn't deprecated and doesn't need replacing.

Most of the table above is a silent break: an old prop name that's no longer in the component's types lands as an inert extra attribute (or, for min/max aliases, the constraint just stops being enforced) instead of throwing. TypeScript callers get a compile error instead. #target is the one slot case — content in a leftover <template #target> silently stops rendering.

Trigger slot props ​

#trigger, #prefix, #suffix, and #actions receive open, setOpen, close, and disabled, alongside their picker-specific fields. TimePicker's #suffix follows. close() is shorthand for setOpen(false).

displayLabel and inputValue are unchanged. Replace toggle() with setOpen(!open) and toggle(value) with setOpen(value).

<!-- Before -->
<template #trigger="{ togglePopover, isOpen }">
  <Button :class="isOpen && 'ring-2'" @click="togglePopover" />
</template>

<!-- After -->
<template #trigger="{ open, setOpen }">
  <Button :class="open && 'ring-2'" @click="setOpen(!open)" />
</template>

Behavior changes that apply even if you don't touch your code:

• DateRangePicker emits a [from, to] tuple. Update handlers that called .split(',') on the value.
• DateRangePicker.modelValue is string[] on the way in too. A stored v0 "from,to" string is read positionally, so the picker silently opens with nothing selected. Convert stored values with .split(',') before binding.
• DateTimePicker no longer auto-closes on date click. Close from @update:modelValue or add an #actions Apply button.
• The popover footer and auto Clear button were removed. Render an explicit Clear inside #actions if you relied on it.
• DateRangePicker.clearable now defaults to true, and nothing on DateRangePicker reads it — emptying the input always clears the range. DatePicker and DateTimePicker still honour :clearable="false".
• useDatePicker and its helpers (getDate, getDatesAfter, getDaysInMonth, isLeapYear) are deleted — the import fails. Nothing in the picker components used them; drop the import.

TimePicker emits: open, close, input-invalid, invalid-change ​

update:open carries the open and the close, with the state in the payload. input-invalid and invalid-change are gone with nothing in their place: typed text that does not parse reverts to the last valid value, which the user sees.

<!-- Before -->
<TimePicker
  @open="onOpen"
  @close="onClose"
  @input-invalid="showHint"
  @invalid-change="setInvalid"
/>

<!-- After -->
<TimePicker @update:open="(open) => (open ? onOpen() : onClose())" />

A leftover @open is silent in JavaScript: it lands as an inert listener and never fires. TypeScript reports it, because TimePickerEmits is narrowed (and now exported). Variant on TimePicker is an alias of the shared InputVariant, not a second scale.

DateRangePicker v-model is DateRangeValue ​

The prop was string[], which let a one-element array in. Both sides are DateRangeValue now — [from, to] or []. TypeScript reports a ref<string[]> bound to the model.

// Before
const range = ref<string[]>([])

// After
import type { DateRangeValue } from 'frappe-ui'
const range = ref<DateRangeValue>([])

Picker template refs, styling hooks and ARIA ​

All four pickers expose { open, close, focus }. They used to expose open() alone. open() is a no-op while the picker is disabled.

<script setup lang="ts">
import { useTemplateRef } from 'vue'
const picker = useTemplateRef('picker')
</script>

<template>
  <DatePicker ref="picker" v-model="date" />
  <Button label="Pick a date" @click="picker?.open()" />
</template>

Additive, and worth knowing if you style or test the pickers: the chevron carries data-slot="chevron", and the <input> carries role="combobox", aria-haspopup (dialog on the date pickers, listbox on TimePicker) and aria-expanded. The <input> keeps data-slot="control" — trigger names the selection family's box only.

MonthPicker ​

MonthPicker is deleted — the import fails.

Its model was one string holding both parts, "<Month> <Year>" (for example "January 2026"), written by a popover that toggled between a month grid and a year grid. Nothing in v1 reproduces that, so pick the replacement that matches what your code reads off the value:

• Month and year: use DatePicker and format the value yourself, or pair two Selects.
• Month only: use Select with month options.

<!-- Before -->
<MonthPicker v-model="month" />
<!-- month === 'January 2026' -->

<!-- After -->
<Select
  v-model="month"
  :options="[
    { label: 'January', value: '01' },
    { label: 'February', value: '02' },
    // ...
  ]"
/>
<!-- month === '01' — the year is no longer part of the value -->

Selection family (Dropdown / Select / Combobox / MultiSelect) ​

Upgrade all three pickers together. They share an option shape and a slot vocabulary, and most apps use more than one.

Nothing here was deleted for an alias — the removed props, option keys and slot props are gone outright. Most fail quietly; see each subsection.

Shared ​

Option values are string | number everywhere. Select no longer accepts bigint or object values.

Select ​

The empty value is a silent break. Select emitted undefined and Combobox emitted null, so one single-value family had two answers for "nothing selected". Both are null now.

// Before
watch(value, (v) => {
  if (v === undefined) reset()
})

// After
watch(value, (v) => {
  if (v === null) reset()
})

clear() and the clear slot prop both write null. MultiSelect keeps [], because an empty array is what its consumers iterate. An empty string is still a real value, so a "None" row with value: '' round-trips unchanged.

Neither component emits anything on mount, so a model that starts as undefined stays undefined until the user picks an option or clears one. Both read undefined as "nothing selected", so the placeholder renders either way. Initialize the ref with null if the value is compared, sent to the server, or watched for the empty case.

SelectionOption and SelectionGroup are exported from the root, so a wrapper around any of the three can name its option shape once. The component-specific types stay.

Combobox ​

MultiSelect ​

Dropdown and ContextMenu ​

All three behavioral removals are silent in plain-JS apps — the old code still runs and renders wrong instead of failing — so check each one. TypeScript callers get errors instead: items and component stay in the option types as never, and placement is gone from DropdownProps altogether. A dev-mode console warning also fires when placement, items or component reaches the menu at runtime.

placement is ignored now. The menu falls back to align="start", so a right-aligned menu quietly moves left:

<!-- Before -->
<Dropdown :options="options" placement="right" />
<Dropdown :options="options" placement="center" />

<!-- After -->
<Dropdown :options="options" align="end" />
<Dropdown :options="options" align="center" />

A { group, items } entry disappears — the group resolves to zero options and is dropped, leaving the rest of the menu intact:

// Before
const actions = [
  { group: 'Edit', items: [{ label: 'Rename', onClick: rename }] },
]

// After
const actions = [
  { group: 'Edit', options: [{ label: 'Rename', onClick: rename }] },
]

A component: row renders as a plain action row using its label, which for most of these rows is empty:

// Before
{ component: h(Button, { theme: 'red' }, () => 'Delete') }

// After
{
  label: 'Delete',
  slots: {
    item: () => h(Button, { theme: 'red' }, () => 'Delete'),
  },
}

These apply identically to ContextMenu, which shares the option shape (ContextMenuComponentOption is removed with DropdownComponentOption).

Custom rows ​

Select and MultiSelect lost #option; Combobox and MultiSelect lost render and slotName. They were the same idea — hand the whole row to the consumer. All three are replaced by region slots on a row the component owns.

<!-- Before: one slot for the whole label area -->
<Select v-model="chartType" :options="options">
  <template #option="{ option }">
    <div class="flex items-center gap-2">
      <component :is="option.icon" class="size-4" />
      <span>{{ option.label }}</span>
    </div>
  </template>
</Select>

<!-- After: one slot per region -->
<Select v-model="chartType" :options="options">
  <template #item-prefix="{ item }">
    <component :is="item.icon" class="size-4" />
  </template>
  <template #item-label="{ item }">{{ item.label }}</template>
</Select>

An icon is rendered from option.icon automatically now, so the common case needs no slot at all — set icon and drop both templates.

Combobox's render moves the same way: the function form becomes slots.item, and the object form maps to slots key for key. Use these for lists built in JavaScript, where no template is in reach:

const users = fetchedUsers.map((user) => ({
  label: user.name,
  value: user.id,
  slots: {
    prefix: ({ item }) => h(Avatar, { image: item.image, class: 'size-4' }),
  },
}))

Full-row takeover is still there — slots.item, or the #item template slot.

Custom options on Combobox ​

Two renames land on the same option object:

// Before
{
  type: 'custom',
  key: 'create-new',
  slotName: 'create-new',
  onClick: ({ searchTerm }) => createItem(searchTerm),
  condition: ({ searchTerm }) => Boolean(searchTerm),
}

// After
{
  type: 'custom',
  key: 'create-new',
  slot: 'create-new',
  onClick: ({ query }) => createItem(query),
  condition: ({ query }) => Boolean(query),
}

The slot the row lands in is renamed with it. #create-new becomes #item-create-new, and it receives { item, query, selected } instead of { option, searchTerm }. onClick and condition keep their names.

If you used allowCustomValue ​

Combobox had a prop that accepted the typed text as the value and drew a built-in Create "…" row. It is gone. It could not do anything a custom row cannot, and it hardcoded the row — no way to change the label, add an icon, or say when it appears.

Build the row instead. It commits on click and on Enter, because Enter picks the highlighted row:

<script setup>
const value = ref('')
const people = ref(['John Doe', 'Jane Doe'])

const options = computed(() => [
  ...people.value.map((p) => ({ label: p, value: p })),
  {
    type: 'custom',
    key: 'create',
    label: 'Create',
    slot: 'create',
    condition: ({ query }) =>
      Boolean(query.trim()) && !people.value.includes(query.trim()),
    onClick: ({ query }) => {
      value.value = query.trim()
    },
  },
])
</script>

<template>
  <Combobox v-model="value" :options="options">
    <template #item-create="{ query }">Create "{{ query }}"</template>
  </Combobox>
</template>

A modelValue that matches no option is kept regardless — the trigger falls back to the raw string — so nothing else changes.

dialog.prompt's allowCreate field option is unaffected; it now builds this row internally.

If you filter on the server ​

Combobox and MultiSelect filter their options in the browser by default. When the options already come back from a search endpoint, that filters them a second time and drops fuzzy, ranked, or id-based matches. Pass :filterable="false" to turn it off. Apps that forked the component for this reason can move back.

For the removed Autocomplete, see Autocomplete (removed).

Popover / HoverCard / Tooltip ​

The v0 Popover API is removed in 1.0.0. Nothing is aliased and nothing warns — Vue drops an unknown prop or slot without complaining, so a missed call site renders a popover with no trigger, or an empty one. Check every <Popover> in your app.

Two more changes have no prop to grep for. v0 always set the panel's min-width to the trigger's width; v1 does it only under matchTriggerWidth, so a panel that leaned on that now shrinks to its content. And the panel no longer teleports into a #frappeui-popper-root div — reka portals it to body, or to the host's portal target. Delete any CSS or document.querySelector aimed at that id; nothing creates it now.

Trigger and content slots ​

#target did not wire anything — you called togglePopover yourself. #trigger renders through reka's PopoverTrigger as-child, which brings the click handler, keyboard support and aria-expanded with it. Keeping your click handler makes the popover toggle twice and stay shut.

<!-- Before -->
<Popover placement="bottom-end">
  <template #target="{ togglePopover }">
    <Button label="Filter" @click="togglePopover" />
  </template>
  <template #body-main="{ close }">
    <FilterPanel @done="close" />
  </template>
</Popover>

<!-- After -->
<Popover side="bottom" align="end">
  <template #trigger>
    <Button label="Filter" />
  </template>
  <template #default="{ close }">
    <FilterPanel @done="close" />
  </template>
</Popover>

#body rendered outside the panel shell, so it maps to #default plusbare — without bare your content ends up inside a second panel.

<!-- Before -->
<Popover>
  <template #body><EmojiPicker /></template>
</Popover>

<!-- After -->
<Popover bare>
  <EmojiPicker />
</Popover>

Driving the popover yourself ​

If your trigger needs custom timing (a delayed open, a drag that must not open it), bind open and accept only closes, so the trigger's own toggle cannot open it behind your back:

<Popover :open="isOpen" @update:open="(value) => !value && (isOpen = false)">
  <template #trigger>
    <div @click="onClick">…</div>
  </template>
</Popover>

Slot props ​

#trigger and #default receive { open, setOpen, close }.

open is now the boolean state, which is what it already means on Dropdown, Select, MultiSelect, HoverCard and Sidebar. It used to be a method on Popover alone.

This one is silent and worth grepping for: a destructured isOpen becomes undefined, so a class bound to it stops applying with no error.

<!-- Before -->
<template #trigger="{ isOpen }">
  <Button :class="isOpen && 'ring-2'" label="Filter" />
</template>

<!-- After -->
<template #trigger="{ open }">
  <Button :class="open && 'ring-2'" label="Filter" />
</template>

Most triggers need nothing at all — #trigger wires its own click, so the open() method it used to hand out had no callers. setOpen is there for the cases that drive it by hand.

Attributes are not inherited ​

<Popover class="…"> and <Popover :style="…"> used to land on a wrapper the legacy #target rendered. #trigger is as-child and renders no wrapper, so those attributes now go nowhere. Move them onto the element inside #trigger.

Hover panels ​

Hover-driven panels move to the HoverCard component. hoverDelay and leaveDelay now use milliseconds; change 0.5 to 500 and 0.3 to 300. Tooltip and TooltipProvider delays use the same unit. HoverCard keeps its 300ms default.

Tooltip ​

All three are silent — the tooltip keeps working, it just points the wrong way, loses the styling, or comes up empty. arrowClass was documented as the arrow's fill, but was mostly used to nudge the bubble's position; offset does that directly.

#default is still the trigger. That is deliberate and is not changing.

<!-- Before -->
<Tooltip text="Preview" placement="bottom" arrow-class="mb-3">
  <Button label="Preview" />
</Tooltip>

<!-- After -->
<Tooltip text="Preview" side="bottom" :offset="12">
  <Button label="Preview" />
</Tooltip>

#body replaced the whole bubble, surface included, so call sites hand-copied the bubble's own classes to get them back. #content renders inside the bubble, so that wrapper goes away:

<!-- Before -->
<Tooltip>
  <template #body>
    <div
      class="rounded bg-surface-gray-10 px-2 py-1 text-xs text-ink-base shadow-xl"
    >
      <span>Hide password</span>
    </div>
  </template>
  <Button icon="eye" />
</Tooltip>

<!-- After -->
<Tooltip>
  <template #content>
    <span>Hide password</span>
  </template>
  <Button icon="eye" />
</Tooltip>

If the content really does bring its own surface — an image preview, say — keep it and add bare:

<Tooltip bare>
  <template #content>
    <img :src="url" class="max-h-40 rounded-4 shadow-xl" />
  </template>
  <span class="truncate">{{ filename }}</span>
</Tooltip>

Inputs ​

Covers TextInput, Textarea, Password, Checkbox, Switch, Rating, Slider. All share the labeling contract (label / description / error / required).

The five rows below <Input> are removed, not aliased. The old names are silently ignored: a Rating with :rating_from="10" renders 5 stars, a :readonly Rating becomes interactive, a Switch @change handler never fires, and labelClasses / Checkbox.padding stop styling anything. Nothing breaks at build time, so grep for these names when upgrading.

<Input> is different: the import fails, so importing call sites break loudly. Apps that register components globally get no import error — the tag just fails to resolve and renders nothing, with a dev-only "Failed to resolve component" warning. Grep the tag, not the import: grep -rn '<Input\b' src.

Slider no longer hardcodes aria-label="Volume". Pass label explicitly so the control is announced correctly.

CircularProgressBar is deleted — the import fails. Use Progress for a linear bar, or render the arc yourself; there is no circular variant in v1.

Input sizes ​

The input size scale is now xs | sm | md | lg. xs is new, and xl is removed.

sm, md and lg render exactly as before. xl was never a bigger box: it drew lg's 40px height with an 18px font, so it was a font override wearing a size name.

<!-- Before -->
<TextInput size="xl" />

<!-- After: pick the height you wanted -->
<TextInput size="lg" />

This applies to every component on the shared input scale: TextInput, Textarea, Password, Rating, Select, Combobox, MultiSelect, ItemListRow, FormControl, the DatePicker family, TimePicker, Duration, and the experimental CodeEditor and MultiEmailInput.

Progress, Slider, Switch, Checkbox, Avatar, Badge, Button and Dialog keep their own scales and are unaffected — <Dialog size="xl"> and <Avatar size="xl"> still work.

A leftover size="xl" no longer drops the geometry. Every input size lookup now falls back to that component's default (sm for the input family) and warns once in dev:

[frappe-ui] TextInput.size="xl" is not a supported value — falling back to
"sm". Supported: xs, sm, md, lg.

TypeScript flags the value at the call site. JavaScript call sites and bound values (:size="config.size") only surface through that warning, so check the dev console after upgrading.

FormControl.size widens the other way: it accepted only sm | md and now takes the whole scale. type="checkbox" renders on the narrower toggle scale, so size="lg" there is clamped to md rather than falling off the end.

Form typography — 13px labels, descriptions and Textarea text ​

Labels, descriptions and Textarea text are a fixed 13px, and labels and descriptions are ink-gray-6. Nothing to change in your source — this is a rendering change.

The two label implementations used to disagree — InputLabel, which FormControl renders through, was a flat 14px while FormLabel was 12px or 14px depending on size. Both are 13px now, so a FormLabel and a TextInput label finally match.

Textarea size still exists and still matters: it moves padding, corner radius and the minimum height. It no longer moves the type. The single-line input heights do not prescribe a Textarea height, so a lg Textarea is a roomier box of the same 13px prose.

The Textarea value colour is unchanged.

FormLabel — size prop removed ​

With the label size fixed at 13px, FormLabel's size axis was degenerate, so the prop is gone rather than kept as a no-op.

<!-- Before -->
<FormLabel label="Email" size="md" />

<!-- After -->
<FormLabel label="Email" />

size now falls through as a plain HTML attribute, so nothing throws — the label just renders at 13px. TypeScript call sites get a build error.

If you passed size="md" you were getting 14px; you now get 13px. If you relied on the sm default you were getting 12px; you now get 13px. Either way the label lands on the accepted size, so the usual answer is to delete the attribute and keep the new value. To hold a different size, style the label yourself rather than reaching for a prop that no longer exists.

Password — value prop removed ​

value was a deprecated alternate way to set the password, seeding v-model on mount. It's gone. :value now falls through as a plain HTML attribute on the native <input> instead of seeding the model — the field still renders, so nothing throws or warns.

<!-- Before -->
<Password v-model="password" :value="initialValue" />

<!-- After -->
<Password v-model="password" />
<script setup>
password.value = initialValue
</script>

TextInput, Textarea, Password — ref surface ​

TextInput and Textarea handed back { el }, a raw ref on the native element. It's now { focus, inputElement }: call focus(options?) to move keyboard focus, and read inputElement for the native element itself (a computed, so it can't be reassigned). Password gains the same pair — it previously exposed nothing.

This fails late rather than at build time: ref.value.el is undefined, so the next access — ref.value.el.focus() — throws at runtime, far from the upgrade. A typed ref catches it as a build error instead.

<!-- Before -->
<TextInput ref="input" />
<script setup>
function focusIt() {
  input.value.el.focus({ preventScroll: true })
}
</script>

<!-- After -->
<TextInput ref="input" />
<script setup>
function focusIt() {
  input.value.focus({ preventScroll: true })
}
</script>

Duration already exposed focus(); it now takes the same options? parameter as the rest of the family.

focus() is on every input ​

Checkbox, Switch, Slider, RadioGroup, Rating and FormControl expose focus() too. They exposed nothing before. The shape is declared once as the exported InputExposed, so a generic form can type a ref to a control it did not choose:

<script setup lang="ts">
import { ref } from 'vue'
import type { InputExposed } from 'frappe-ui'

const fields = ref<InputExposed[]>([])
function focusField(index: number) {
  fields.value[index]?.focus()
}
</script>

FormControl forwards focus() to whichever control its type resolved to.

Focus lands on the element Tab reaches, not on the container: Slider focuses the thumb, RadioGroup the selected option (the first enabled one when nothing is selected), and Rating the selected star (the first star when the value is empty), except in half-star mode where the whole control is one slider.

Attributes go to the control, class and style to the wrapper ​

An input has a layout wrapper and an interactive element. class and style go to the wrapper; name, aria-*, data-* and listeners go once to the interactive element.

This is a silent break in four components:

Two things to audit. A listener now fires once, from the control:

<!-- fired twice before; fires once now, and not from the padded row -->
<Checkbox padded label="Agree" @click="onClick" />

And a CSS rule written against the wrapper no longer matches a data-* you passed in. Move the selector to the control, or keep using class.

TextInput, Textarea, Password, Select, Combobox, MultiSelect, Slider, FormControl, Duration and the date pickers already followed the rule and are unchanged.

Rating defaults to size="sm" ​

Every other input defaults to sm. A <Rating> with no size now renders smaller. Pass size="md" to keep the old size.

<!-- Before: rendered md -->
<Rating v-model="score" />

<!-- After: same pixels -->
<Rating v-model="score" size="md" />

Silent, and there is no codemod: an omitted prop is not a token a codemod can find, and rewriting every <Rating> in an app to pin the old default would be worse than the change. Three v1 app sites were already passing a smaller size by hand.

Duration forwards #label and #description ​

They used to be dropped. If you passed either slot to Duration, it renders now — check that it does not duplicate a label or description prop you also set.

FormControl no longer forwards variant to a checkbox ​

A checkbox draws no container surface, so it has no variant. The forwarded value used to land on the <input> as a stray variant="subtle" attribute. The type routes are unchanged: date renders DatePicker, time renders TimePicker, and a native date field is <TextInput type="date" />.

data-slot="label" on FormLabel ​

FormLabel carries the hook InputLabel already rendered, so one selector reaches every label in the library. Additive.

Input types the root publishes ​

Additive, except for two removals:

• InputExposed — the template-ref shape every input implements.
• PickerExposed — InputExposed plus open and close, for the four pickers.
• SelectionOption, SelectionGroup — the shared option shapes.
• Dayjs — the date pickers hand one to formatter, disabledDate and the setter slot props, so the type has to be nameable.
• DateRangeValue — both sides of DateRangePicker's v-model.
• InputLabelingProps — for a wrapper that forwards label / description / error / required.

DatePicker's barrel lists its public types instead of re-exporting the whole module. DatePickerViewMode and DatePickerDateObj were calendar internals the wildcard published; they leave the root and the import fails. Nothing replaces them — they described the calendar's internal state.

SelectEmits, ComboboxEmits and MultiSelectEmits no longer redeclare the model events defineModel already declares, and RadioGroupEmits says RadioValue | undefined, which is what an unbound group starts at. A handler typed against the old shapes still compiles. Type a model handler off the model instead: (value: SelectOptionValue | null | undefined) => void. The extra undefined is there because the model prop is optional; neither Select nor Combobox ever emits it.

FileUploader ​

FileUploader reached structural bar in 1.0.0: TypeScript, flat props, and a security fix to the default it shares with useFileUpload / FileUploadHandler.

Uploads default to private ​

useFileUpload() and FileUploadHandler now resolve an upload with no stated private / is_private to private, not public. Coming from v0, FileUploader flips with them: it had no private prop at all and inherited the public default. It has uploaded private by default since v1.0.0-beta.21, so only pre-beta.21 upgrades see the component change.

// Same call, before and after — the result changes:
await useFileUpload().upload(file, {})
await new FileUploadHandler().upload(file, {})
// Before: is_private=0 (public).  After: is_private=1 (private).

// State the intent explicitly instead of relying on the default:
await useFileUpload().upload(file, { private: false }) // public
await useFileUpload().upload(file, { private: true }) // private

If your app serves an uploaded file with no session — an avatar in an email digest, an image embedded on a public page — audit every call that omits private / is_private before upgrading. A file that flips to private returns 403 to a session-less request instead of the image.

Uploads reject an UploadError ​

upload, useFileUpload and FileUploadHandler reject with an exported UploadError instead of a plain Error, and state.error is typed with it. Branch on error.kind ('file-size' | 'network' | 'server' | 'abort') rather than matching the message text. A server failure also carries status, messages (the parsed server messages) and the raw response.

import { UploadError, upload } from 'frappe-ui'

try {
  await upload(file, { doctype: 'ToDo', docname: 'TODO-0001' })
} catch (error) {
  if (error instanceof UploadError && error.kind === 'file-size') {
    showError('That file is too large.')
  } else {
    throw error
  }
}

Existing catch blocks keep working: UploadError is an Error and its message is unchanged. FileUploadHandler no longer leaves the promise open when the request aborts; it rejects like the other two paths.

An aborted upload rejects an UploadError, not a DOMException ​

Silent break. upload() and useFileUpload() take an options.signal. When that signal fired, they rejected with new DOMException('Upload cancelled', 'AbortError'). They now reject an UploadError with kind: 'abort'. The message text is the same, but error.name is 'UploadError' instead of 'AbortError', and error instanceof DOMException is false. A catch block that tells a cancel from a failure by either of those stops matching, so a cancelled upload is reported to the user as an error.

// Before
try {
  await upload(file, { signal: controller.signal })
} catch (error) {
  if (error.name === 'AbortError') return // user cancelled
  showError(error.message)
}

// After
import { UploadError } from 'frappe-ui'

try {
  await upload(file, { signal: controller.signal })
} catch (error) {
  if (error instanceof UploadError && error.kind === 'abort') return
  showError(error.message)
}

The is_private upload option is removed ​

useFileUpload and FileUploadHandler took private and is_private for the same decision, with private winning. Only private is left, and it is a boolean. This is loud in TypeScript and silent in JavaScript, where an is_private you still pass is ignored and the upload falls back to the private default — so a public upload written as { is_private: 0 } becomes private.

// Before
await upload(file, { is_private: 0 })

// After
await upload(file, { private: false })

The is_private field on the uploaded file record the server returns is unchanged.

uploadArgs → flat props ​

The single uploadArgs object prop is gone. Its commonly-used fields are now flat props on the component:

<!-- Before -->
<FileUploader :uploadArgs="{ private: false, folder: 'Attachments' }" />

<!-- After -->
<FileUploader :private="false" folder="Attachments" />

This is silent: uploadArgs isn't a recognized prop anymore, so Vue passes it through as an inert HTML attribute on the root element. Nothing throws — the options it carried just stop applying, and (combined with the default flip above) a uploadArgs="{ private: false }" override that used to make an upload public silently starts uploading private instead. grep every <FileUploader> for uploadArgs= / :upload-args= and move each field to its flat prop.

file_url, method, type, params, max_width / max_height, and upload cancellation (signal) have no flat-prop equivalent — they had no measured use on the component. Use useFileUpload() directly for those.

Template ref — inputRef removed ​

FileUploader hands back nothing through a template ref, per ADR-0012. inputRef() (a function, despite the name) is gone with nothing in its place — the openFileSelector slot prop already covers what it opened.

<!-- Before -->
<FileUploader ref="uploader" />
<script setup>
uploader.value.inputRef().click()
</script>

<!-- After -->
<FileUploader v-slot="{ openFileSelector }">
  <Button @click="openFileSelector">Upload</Button>
</FileUploader>

Default slot's error prop — always a string ​

The default slot's error prop is string | null, no longer unknown. Upload failures were always normalized to a message string; validation failures (a validateFile prop returning an Error) were not, so error could previously be an Error object too. Both paths normalize to a message string now.

<!-- Before: had to guard against error being a string or an Error -->
<template #default="{ error }">
  {{ typeof error === 'string' ? error : error?.message }}
</template>

<!-- After: error is always a string -->
<template #default="{ error }">
  {{ error }}
</template>

This is silent: a slot that only ever did error.message (assuming the Error shape) now renders undefined instead of the validation message.

failure also fires for validation now. A validateFile that returns a message or throws emits failure with that value; v0 only wrote it to the slot's error. An existing @failure handler starts seeing validation rejections alongside upload errors.

fileToBase64 and the size-limit helpers — no longer exported ​

fileToBase64 is no longer exported from frappe-ui; the import fails at build time. There were no external call sites at the v1 sweep. Computing a file's base64 representation yourself is a few lines of FileReader.readAsDataURL. The size-limit helpers (formatBytes, getMaxFileSize, fileSizeLimitMessage) were only ever exported during the 1.0.0 betas and are internal now.

Divider ​

This is a silent break: handler is dropped as an unknown key, so the action button still renders and does nothing on click.

List family ​

Run npx list-v1 . from each app that imports components from frappe-ui/list. It updates selectors anchored to [data-slot="list-row"], Tailwind state variants on imported ListRow components, and the two statically named slots below:

-<ListGroup><template #header>Open</template></ListGroup>
+<ListGroup><template #label>Open</template></ListGroup>
 <ListHeaderCellSort align="end">
-  <template #suffix="{ direction }">…</template>
+  <template #sort-indicator="{ direction }">…</template>
 </ListHeaderCellSort>

Every ListRowBase now has data-state="active" or "inactive". Selection and interactivity are independent boolean attributes: data-selected and data-interactive. ItemListRow keeps its existing runtime contract. The sort-indicator slot keeps its edge-aware placement, including the leading edge for align="end".

The codemod leaves same-named local or globally registered components alone. If one still contains an old slot name, it reports the ambiguity for a manual check. It also exits non-zero and leaves a file unchanged when it finds a dynamic slot under either renamed component. These slot renames are silent breaks because Vue drops content passed under an unknown name.

After the codemod, grep for group-data-[active], unanchored data-state="selected" / data-active selectors, render-function slot keys named header or suffix, and dynamic slots. Those forms need a manual check because the tool cannot prove which component owns them.

ListRows.virtual is now a boolean. Move the object's overscan field to the new top-level overscan prop and set height on the parent List with rowHeight. Stop importing ListVirtualOptions or useVirtualRows; virtualization is component-owned. The ListRows slot also receives independent selected and active booleans.

ListView — moved to frappe-ui/experimental ​

ListView is not core v1 surface. It moves out of the root export to frappe-ui/experimental (P14 — no stability promise) and stays there until frappe-ui/list reaches full functional parity. The import fails at the root; switch the subpath:

// Before
import { ListView, ListRow, ListHeader } from 'frappe-ui'

// After
import { ListView, ListRow, ListHeader } from 'frappe-ui/experimental'

Every other name in the family moves the same way: List, ListEmptyState, ListFooter, ListGroupHeader, ListGroupRows, ListGroups, ListHeaderItem, ListRowItem, ListRows, ListSelectBanner. Nothing about the component itself changed — only where it's imported from.

Calendar — moved to frappe-ui/experimental ​

Calendar is not core v1 surface. It moves out of the root export to frappe-ui/experimental (P14 — no stability promise) and parks there, API unchanged, until a redesigned calendar family replaces it. The import fails at the root; switch the subpath:

// Before
import { Calendar, CalendarColorMap } from 'frappe-ui'

// After
import { Calendar, CalendarColorMap } from 'frappe-ui/experimental'

Every other name in the family moves the same way: CalendarActiveEvent and the types CalendarActions, CalendarCellClickData, CalendarConfig, CalendarEvent, CalendarMode, CalendarPublicProps, CalendarTimeFormat, GroupedCalendarEvents. Nothing about the component itself changed — only where it's imported from.

Charts (v1) — moved to frappe-ui/experimental ​

The first chart family is not core v1 surface. AxisChart, DonutChart, ECharts, FunnelChart, NumberChart and useAxisChartOptions move out of the root export to frappe-ui/experimental (P14 — no stability promise) and park there, API unchanged, while apps migrate. The import fails at the root; switch the subpath:

// Before
import { AxisChart, DonutChart, NumberChart } from 'frappe-ui'

// After
import { AxisChart, DonutChart, NumberChart } from 'frappe-ui/experimental'

Nothing about the components changed — only where they're imported from. Apps that spread content from frappe-ui/tailwind keep their styles automatically.

For new code, use frappe-ui/charts instead. It is the replacement family and draws everything the old one did. Its props are flat and name the columns of your rows, so a config object becomes props:

<!-- Before -->
<AxisChart
  :config="{
    data: rows,
    xAxis: { key: 'week' },
    series: [{ name: 'balance', type: 'area' }],
  }"
/>

<!-- After -->
<AreaChart :data="rows" x="week" y="balance" />

The port is not a pure rename. Four config keys have no same-named prop, so a rename-only port drops them silently — no build error, no type error, just a chart that scales or draws differently:

Combo charts survive the port: seriesConfig[key].type takes 'bar' | 'line' | 'area', and seriesConfig[key].axis: 'y2' moves one series to the second value axis, configured with the chart-level y2Axis prop.

Sprite icons — moved to frappe-ui/experimental ​

The sprite-based Icon, IconPicker, and spritePlugin are not core v1 surface. They move from frappe-ui/icons to frappe-ui/experimental (P14 — no stability promise). The old import fails; switch the subpath:

// Before
import { Icon, IconPicker, spritePlugin } from 'frappe-ui/icons'

// After
import { Icon, IconPicker, spritePlugin } from 'frappe-ui/experimental'

Nothing about the components changed — only where they're imported from. Apps that spread content from frappe-ui/tailwind keep IconPicker styles automatically — no Tailwind change needed. Note that root frappe-ui exports a different Icon; alias one if you import both, e.g. import { Icon as SpriteIcon } from 'frappe-ui/experimental'. The named SFC icons (CircleCheckIcon, HelpIcon, ...) stay on frappe-ui/icons. For new code, use lucide-* classes — they are the canonical way to render icons.

Alert ​

Alert is stateless now — it has no v-model and never hides itself. The parent renders it with v-if and reacts to @dismiss. Layout is content-driven: a description or a second action switches it to the banner layout; there is no variant prop. See the Alert component page for the full API.

Every row is a silent break: Vue drops the unknown prop or slot with no error. The old v-model is the one to check first — a dismissed alert now stays on screen until the parent hides it:

<!-- Before -->
<Alert v-model="showAlert" title="Payment failed" theme="yellow">
  <template #footer>
    <Button label="Retry" @click="retry" />
  </template>
</Alert>

<!-- After -->
<Alert
  v-if="showAlert"
  title="Payment failed"
  theme="amber"
  dismissible
  :primary-action="{ label: 'Retry', onClick: retry }"
  @dismiss="showAlert = false"
/>

An action is ButtonProps plus an onClick that receives { dismiss } — call context.dismiss() to emit the alert's dismiss event:

const primaryAction = {
  label: 'Retry',
  onClick: ({ dismiss }) => {
    retry()
    dismiss()
  },
}

If the alert was really a promotional card in a sidebar, use the new SidebarCard component instead.

Badge ​

theme="orange" is removed. It was a deprecated alias that resolved to amber, so the replacement renders the same badge it always did.

How the break shows up depends on whether the call site is typed:

• TypeScript: loud. vue-tsc rejects the value, because the theme prop union no longer accepts the string. You get a compile error, not a surprise in production.
• JavaScript and bound values: silent. The badge renders in the default gray theme and logs a one-time dev-mode warning naming the component, the prop and the value. Production logs nothing.

[frappe-ui] Badge.theme="orange" is not a supported value — falling back to
"gray". Supported: gray, blue, green, amber, red, violet.

A missed site is therefore a grey badge, not a broken page. Badge used to index a class map by theme and then index the result again by variant, so an unknown theme threw TypeError: Cannot read properties of undefined mid-render and took the parent render with it. All three of theme, variant and size now fall back to their defaults instead.

Do not rely on the fallback. It is a safety net for the upgrade, not a supported way to pass a colour — a grey badge where a coloured one belongs is still a bug, and the dev warning is the only thing that will tell you.

<!-- Before -->
<Badge theme="orange" label="In Progress" />

<!-- After -->
<Badge theme="amber" label="In Progress" />

Check bound themes too, not only literal attributes. A status-to-theme map or a computed that returns 'orange' degrades the same way, and neither vue-tsc nor a grep for theme="orange" finds it:

// Before
const themeByStatus = { open: 'orange', closed: 'green' }

// After
const themeByStatus = { open: 'amber', closed: 'green' }

Watch for orange as a fallback, which affects more sites than it looks — every caller that omits a theme lands on it:

<!-- Before — every caller without `badge.theme` renders grey -->
<Badge :theme="badge.theme ?? 'orange'" />

<!-- After -->
<Badge :theme="badge.theme ?? 'amber'" />

If your app keeps its own colour vocabulary and cannot rename orange at the source, translate at the boundary instead of passing it through:

const badgeTheme = tone === 'orange' ? 'amber' : tone

Sidebar ​

Sidebar is a bare frame — compose SidebarHeader / SidebarSection / SidebarLabel / SidebarItem in its default slot instead of passing config-object props. See the Sidebar component page for the full API.

Every removal here is a silent break. A dropped prop (header, sections, items, isActive) becomes a fall-through attribute on the component's root element, and content passed to the removed #sidebar-item slot is discarded — no build error, no type error, no warning. The sidebar renders as an empty frame. Grep for :header=, :sections=, :items=, #sidebar-item and isActive on these five components after upgrading.

<!-- Before -->
<Sidebar
  :header="{ title: 'Frappe CRM', subtitle: 'crm.frappe.io', menuItems }"
  :sections="[
    {
      label: '',
      items: [{ label: 'Leads', to: '/leads', icon: 'lucide-user-plus' }],
    },
    { label: 'Views', collapsible: true, items: viewItems },
  ]"
/>

<!-- After -->
<Sidebar>
  <SidebarHeader title="Frappe CRM" subtitle="crm.frappe.io" :menu-items="menuItems" />
  <div class="flex-1 overflow-y-auto px-2">
    <SidebarItem label="Leads" route="/leads" icon="lucide-user-plus" />
    <SidebarSection label="Views" collapsible>
      <SidebarItem v-for="item in viewItems" :key="item.label" v-bind="item" />
    </SidebarSection>
  </div>
</Sidebar>

Sidebar no longer wraps the middle list in a scroll container or applies any padding — that's app-owned now (see the component page's Collapse section for the full composition contract).

SettingsDialog ​

Open state moves from the unnamed v-model to v-model:open, the name every other overlay in the library uses.

This is a silent break: Vue accepts the unknown modelValue prop with no error, so the dialog just never opens.

<!-- Before -->
<SettingsDialog v-model="showSettings" v-model:tab="tab">…</SettingsDialog>

<!-- After -->
<SettingsDialog v-model:open="showSettings" v-model:tab="tab">…</SettingsDialog>

v-model:tab is unchanged. Replace shortcut with keyboardShortcut; it defaults to "Mod+Shift+,", and false disables the registration. Unlike Dialog, SettingsDialog has no legacy unnamed-v-model binding to keep — open is the only visibility channel.

navigation-v1 removes bare and statically true shortcut props because the new default preserves their behavior. It converts static false values and reports dynamic boolean expressions for a manual combo-or-false decision.

Tabs ​

The monolithic Tabs is replaced by a composed family: Tabs, TabList, TabTrigger, TabPanel. The model is the trigger value, never an index. See the Tabs component page for the full API.

Run npx navigation-v1 . for the current TabButtons and Tabs active slot/state vocabulary. The broader v0 Tabs composition rewrite remains a hand edit. tokens-v2 rewrites Tailwind token names only — it never touches a component, prop, or slot name, so grep for the remaining old names rather than waiting for the build to tell you.

| Before | After | | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | ---------- | | v-model="tabIndex" (index) | v-model="tab" (trigger value) | | :tabs="[{ label, icon }]" (required) | <TabTrigger> children; the tabs shorthand stays for generated sets | | label implied the value | value is required on every trigger | | as="div" | removed — compose and style the container directly | | <template #tab-item="{ tab, selected }"> | TabTrigger props (icon, iconLeft, route) and slots (#prefix, default, #suffix), or #tab-label in shorthand mode | | #prefix / #label / #suffix / #panel alongside :tabs | #tab-prefix / #tab-label / #tab-suffix / #tab-panel — every shorthand slot carries the tab- prefix; composed TabTrigger keeps plain #prefix / #suffix. An unknown slot name renders nothing, nothing throws | | extra fields on a tabs item ({ value, content }) | data: { content }, read as tab.data.content — extra keys are now a type error | | <template #tab-panel="{ tab }"> | <TabPanel :value> children; the shorthand slot is #tab-panel, back on its v0 name (it was briefly #panel in the betas) | | Tab.route string + hand-rolled route sync | route: RouteDestination on the trigger; selection derives from the route | | stale-index clamps for conditional tabs | built in: a stale model falls back to the first visible trigger and emits | | [&_[role='tablist']]:px-4 class blobs | <TabList class="px-4"> — the app owns the element | | built-in flex and overflow defaults | none — see Scrolling below; the tabs stop scrolling and overflow instead | | iconRight on a trigger or a tabs item | <template #suffix> on a composed TabTrigger, <template #tab-suffix> in shorthand mode — the icon silently stops rendering, nothing throws | | slot prop selected / checked | active | | data-state="checked|unchecked" | data-state="active|inactive" |

<!-- Before -->
<Tabs v-model="tabIndex" :tabs="[{ label: 'Emails' }, { label: 'Calls' }]">
  <template #tab-item="{ tab, selected }">
    <span :class="selected ? 'text-ink-gray-9' : ''">{{ tab.label }}</span>
  </template>
  <template #tab-panel="{ tab }">
    <div>{{ tab.label }} content</div>
  </template>
</Tabs>

<!-- After -->
<Tabs v-model="tab">
  <TabList>
    <TabTrigger value="emails" label="Emails" />
    <TabTrigger value="calls" label="Calls" />
  </TabList>
  <TabPanel value="emails">Emails content</TabPanel>
  <TabPanel value="calls">Calls content</TabPanel>
</Tabs>

Tabs exposes nothing on the template ref, and TabList gains full variant parity with TabButtons: underline, subtle, ghost, browser-tab.

Scrolling ​

v0 shipped layout defaults: the root was flex flex-1 overflow-hidden flex-col, the tablist overflow-x-auto, and every panel flex flex-col overflow-auto. v1 sets none of them, because they broke as often as they helped — a Tabs that force-grows to fill its parent is wrong everywhere the tabs are not the whole screen.

Nothing throws. Inside a height-constrained container the panel stops scrolling and overflows instead. Check any call site that relied on it.

In composed mode the app owns the elements, so put the classes back where you want them:

<Tabs v-model="tab" class="flex min-h-0 flex-1 flex-col">
  <TabList class="overflow-x-auto">…</TabList>
  <TabPanel value="emails" class="min-h-0 flex-1 overflow-auto">…</TabPanel>
</Tabs>

In shorthand mode the generated elements are not yours to class, so reach them through their data-slot hooks:

<Tabs
  v-model="tab"
  :tabs="items"
  class="min-h-0 flex-1 [&_[data-slot=tab-list]]:overflow-x-auto [&_[data-slot=tab-panel]]:min-h-0 [&_[data-slot=tab-panel]]:flex-1 [&_[data-slot=tab-panel]]:overflow-auto"
/>

TabButtons ​

TabButtons keeps its radiogroup role — a value input, not a panel switcher — and aligns its vocabulary with the Tabs family. See the TabButtons component page for the full API.

Every prop rename here is a silent break: an unknown prop lands in $attrs and is spread onto the radiogroup root, so a TabButtons still on :buttons renders an empty track with no build error, type error, or warning. The destination codemod handles statically named component props only. Grep for :buttons, type=, direction=, hideLabel, tooltip, and non-string labels in option data.

Data fetching (useDoctype / useList) ​

The write methods on useDoctype (insert, delete, setValue, runDocMethod, runMethod) and on useList (insert, setValue, delete) used to share one request between all their submits. Each one now sends its own request, so the shared-request members are gone.

Nothing fails to build, so grep for these by hand. There are two failure modes, and one of them is quiet. Calling a removed method throws (delete.execute(), insert.reset()), and so does dotting into one (delete.params.name). A removed data member reads as undefined instead: runMethod.isFetching is always falsy, so a spinner silently never shows and nothing says why.

All eight now have the same five members: submit(), data, error, loading and isLoading().

isLoading() takes whatever identifies one submit:

todos.delete.isLoading(row.name)
todos.setValue.isLoading(row.name)
todos.runDocMethod.isLoading(row.name, 'archive')
todos.runMethod.isLoading('sync_all')
todos.insert.isLoading() // no argument: a new row has no name yet

insert.isLoading() gives the same answer as insert.loading. It is there so every write method reads the same way.

More changes you will not see at build time:

• submit() now resolves with its own response. Code that fired two submits and read the result of the first was receiving the second one's data, or null. If you queued submits to work around that, you can drop the queue.

• data and error belong to the submit that started last, not the one that answered last. A slow submit that comes back after a newer one writes nothing and clears nothing. It still answers its own caller with its own outcome — resolving with its response, or rejecting with its error.

• data is no longer reset to null when a submit fails. It used to be, because the shared request cleared it on any not-ok response. It now keeps the last successful response.

  js

  await todos.setValue.submit({ name: 'TODO-1', status: 'Done' })
  await todos.setValue.submit({ name: 'TODO-2', status: 'Done' }) // fails
  
  todos.setValue.data // still the TODO-1 response
  todos.setValue.error // the failure

  Test error, not data, to tell a failed submit from a successful one. if (!todos.setValue.data) used to mean "the last save failed" and no longer does.

• error is no longer cleared when a submit starts. It used to be, which erased the error of a sibling submit still in flight. It now stands until the newest submit settles. To blank an error banner while a retry runs, hide it on loading yourself.

• submit() rejects on any failure. It resolves with the response, or rejects with the error. A failed validate already rejected; a failed request used to resolve with null. Both reject now.

  js

  // Before
  const doc = await todos.insert.submit({ title: 'Buy milk' })
  if (!doc) return showError(todos.insert.error)
  
  // After
  try {
    const doc = await todos.insert.submit({ title: 'Buy milk' })
  } catch (e) {
    showError(e)
  }

  null no longer means "it failed". A server that answers with null resolves with null, like any other response. Every if (!result) check after a submit() has to become a try / catch or a .catch(), and an unawaited submit() now needs a .catch() or it becomes an unhandled rejection.

• useList's insert and delete now send to the baseUrl you passed to useList. They used to ignore it and hit the current origin. setValue already honoured it, so all three write methods now agree. useDoctype was never affected.

• A stale setValue or delete on the same row no longer writes the shared document and list stores, and no longer triggers useList's auto-refetch. Every request carries a dispatch number, and a store rejects a write that a later-dispatched request already made. Submits with different keys, and keyless submits such as inserts, stay independent and all of their hooks still fire. Nothing to change — this is here so you can drop the workarounds.

useDoc writes and useNewDoc ​

useDoc's setValue, delete and every methods: entry, and all of useNewDoc, held one shared request too. Each submit now sends its own. They keep the full useCall surface — same members, same types — so there is nothing to rename.

One silent behavior change: a second submit no longer cancels the first. Both requests reach the server. If you relied on the abort to drop a superseded save, debounce or guard the call site yourself. data and error follow the same newest-wins rule as useDoctype above, and loading stays true until every submit settles.

Data fetching: writes reject, reads resolve ​

One rule now covers every composable: a write rejects when it fails, a read resolves. A failed write must not let its caller run the success path. A failed read leaves the last value on screen and reports through error.

useDoctype and useList write methods already rejected — see the section above. This change brings the rest in line with them.

Silent. Nothing fails to build. The success path simply stops running, and an unawaited submit() becomes an unhandled rejection.

// Before: the failure fell through to the success path
const doc = await todo.setValue.submit({ status: 'Closed' })
if (!doc) return showError(todo.setValue.error)
toast.success('Saved')

// After
try {
  await todo.setValue.submit({ status: 'Closed' })
  toast.success('Saved')
} catch (error) {
  showError(error)
}

Grep for .submit( and check each site. Three patterns need work:

• if (!result) after a submit() — null is a valid response now, not a failure. Move the handling into a catch.
• a submit() that is not awaited — add .catch(...) or it reaches window.onunhandledrejection.
• a submit() inside a Promise.all — one rejection now fails the whole batch. Use Promise.allSettled if that is not what you want.

error and onError are unchanged: both still fire, whether the call rejects or not. Reads need no change.

useDoc method names cannot shadow the object's own members ​

A methods: key that is already a member of what useDoc returns (doc, error, loading, reload, setValue, delete, and the rest) used to overwrite it silently. It throws at setup now and names the collision. Rename the key and keep the server method name:

// Before: `reload` silently replaced the document's own reload()
useDoc({ doctype: 'ToDo', name, methods: { reload: 'reload_items' } })

// After
useDoc({
  doctype: 'ToDo',
  name,
  methods: { reloadItems: { name: 'reload_items' } },
})

useNewDoc and useDoc methods take fewer options ​

An insert and a document method are writes that run when you call submit(). immediate and refetch are fixed to false for both, and useNewDoc no longer accepts refetch, cacheKey or staleOnError at all.

This is loud in TypeScript and silent in JavaScript, where the values are now ignored. refetch: true was the dangerous one: it re-sent the insert on every keystroke in the form bound to doc.

// Before: an insert per edit to the draft
const draft = useNewDoc('ToDo', { description: '' }, { refetch: true })

// After
const draft = useNewDoc('ToDo', { description: '' })
await draft.submit()

Data fetching (exports) ​

useFrappeFetch is no longer exported. It is the raw createFetch instance useCall, useDoc and useList are built on: it sets the Frappe headers and parses the response, and leaves the URL, the params and the caching to you. Pick the composable that matches what you are fetching.

This is a build failure at the import, so nothing changes silently.

// Before
import { useFrappeFetch } from 'frappe-ui'
const { data } = useFrappeFetch('/api/v2/method/ping').get()

// After
import { useCall } from 'frappe-ui'
const ping = useCall({ url: '/api/v2/method/ping' })

FrappeResponseError is exported now. A Frappe error response raises it — it lands on .error, and the write methods above reject with it. The class was never exported, so you could not tell it apart from a network or parse failure. Narrow it with instanceof and you get title, type, indicator and exception:

import { FrappeResponseError } from 'frappe-ui'

try {
  await todos.insert.submit({ title: 'Buy milk' })
} catch (e) {
  if (e instanceof FrappeResponseError) {
    showError(e.title, e.type)
  } else {
    throw e
  }
}

FrappeRequestError is FrappeResourceError ​

The error type the resource layer raises is renamed. Both errors in the library are server responses, so request versus response named nothing; the name says the layer that raises it now. Only apps on a v1 beta are affected: v0 never exported either name.

FrappeResponseError does not change. The fields on both are the same as before, and there is no alias: importing the old name is a build failure.

// Before
import type { FrappeRequestError } from 'frappe-ui'

// After
import type { FrappeResourceError } from 'frappe-ui'

The two narrow differently, which also does not change. FrappeResponseError is a class, so instanceof works. FrappeResourceError is a type over a plain new Error(...) with fields assigned, so there is no value to test: read the field you need.

try {
  await call('frappe.client.get_list', { doctype: 'ToDo' })
} catch (error) {
  const e = error as FrappeResourceError
  if (e.exc_type === 'PermissionError') showPermissionMessage()
  else throw error
}

FrappeUIError is removed ​

The exported error type for an input's error prop is gone. The prop is typed where it is declared, and a wrapper that forwards it reads the type from InputLabelingProps, which the root now exports.

// Before
import type { FrappeUIError } from 'frappe-ui'
defineProps<{ error?: string | FrappeUIError }>()

// After
import type { InputLabelingProps } from 'frappe-ui'
defineProps<{ error?: InputLabelingProps['error'] }>()

The prop also accepts a string[] now, which is what ErrorMessage.message takes. One array renders one line per entry, and an empty array means no error. Everything that worked before still works: a string, or an Error that may carry messages.

Upload exports ​

UploadError is exported. Every upload failure rejects with it, and useFileUpload's state.error holds it — see FileUploader.

isPrivateUpload and the UploadPrivacy type are removed. They existed for the is_private upload option, which is gone; pass private instead. This is a build failure at the import. No app used either name.

A destination prop is typed RouteDestination ​

Every prop that takes a router destination (Button.route, the Sidebar, Tabs, Breadcrumbs and Menu item types, and the rest) is typed RouteDestination instead of vue-router's RouteLocationRaw. The root exports RouteDestination and RouteLocationObject.

The accepted values do not change: a path string, or an object with name / params / path / query / hash. The owned type exists so the generated API docs print a readable name rather than vue-router's minified internal ones.

Resource and editor barrels name their exports ​

frappe-ui/resources and frappe-ui/editor used export * from their implementation files, which published every name those files happened to export. Both now list what they publish. The names apps import are all still there; an import of an internal helper that was never meant to be public fails at build time.

Tree ​

The Tree was rebuilt from a single recursive node renderer into a stateful forest. It takes a nodes array and scopes its per-row slots as #item-*. Expansion moved off the nodes and into a keyed v-model:expanded, so the tree never writes to the objects you pass in. The options blob is gone — sizing moves to CSS variables. Keyboard navigation, role="tree" ARIA, and opt-in drag-and-drop are new.

Nothing here fails loudly. :node and :options become fall-through attributes, and content passed to the old #node / #label / #icon slots is discarded — the default row renders in its place. A production build renders an empty tree. Three things warn, and only in dev: the now-required nodes prop, the removed per-node expanded field, and the removed boolean form of v-model:expanded (see below). Grep for :node=, :options=, #node, #label and #icon on Tree specifically.

<!-- Before -->
<Tree :node="root" node-key="name" :options="{ defaultCollapsed: false }">
  <template #label="{ node }">{{ node.title }}</template>
</Tree>

<!-- After -->
<Tree :nodes="[root]" node-key="name" v-model:expanded="expanded">
  <template #item-label="{ node }">{{ node.title }}</template>
</Tree>

Expansion is keyed, and the tree stops writing to your nodes ​

v-model:expanded is an array of the keys of the open nodes. A key that is absent means collapsed, so a tree with no bound model renders its roots and nothing else. Drop any expanded field you set on node data — it is no longer read. A dev build warns once when it finds one, and once more if you still pass the old boolean to v-model:expanded; production is silent either way.

<!-- Before — the tree wrote `expanded` back onto your objects -->
<Tree :nodes="nodes" node-key="name" />

<!-- After — expansion lives in your state, as keys -->
<script setup>
const expanded = ref(['src', 'src/components'])
</script>
<Tree :nodes="nodes" node-key="name" v-model:expanded="expanded" />

Every toggle assigns a new array rather than mutating one in place, so shallow watchers, immutable stores and undo logs see the change.

The old boolean expand/collapse-all switch is gone. Call expandAll() / collapseAll() on the component ref instead:

<script setup>
const tree = ref(null)
const expanded = ref([])
</script>

<template>
  <Button @click="tree.expandAll()">Expand all</Button>
  <Tree ref="tree" :nodes="nodes" node-key="name" v-model:expanded="expanded" />
</template>

expand(key), collapse(key) and toggle(key) are exposed too. All five are programmatic, so disabled does not block them.

Drag-and-drop is opt-in: set draggable, gate drops with :move="({ node, target, position }) => …", and persist from @drag-end="(info) => …" — info is { node, from, to, position, oldIndex, newIndex }, or null when the drag is cancelled.

Icons ​

The single recommended way to pass an icon anywhere in the library is a lucide-* string (rendered via the Tailwind mask plugin) or a Component escape hatch (P11). FeatherIcon is removed per ADR-0008 — it shipped @deprecated in code, so nothing marked deprecated ships in 1.0.0.

Breaking, loud: import { FeatherIcon } from 'frappe-ui' and <FeatherIcon> fail at the import. Replace a direct usage with the lucide-* class form:

<!-- Before -->
<FeatherIcon name="plus" class="size-4" />
<!-- After -->
<span class="lucide-plus size-4" aria-hidden="true" />

Feather and lucide share most icon names, so <FeatherIcon name="x"> → <span class="lucide-x"> is usually a direct rename — check each name individually against lucide.dev since a few differ or were renamed.

Breaking, silent: every icon-name prop across the library (Button.icon / iconLeft / iconRight, Dialog.icon, Alert.icon, SidebarCard.icon, Dropdown/ContextMenu item icon, TabButtons options icon / iconLeft, TabTrigger.icon / iconLeft, the Icon component's icon prop) used to render a bare feather-style name (e.g. "edit", "chevron-down") via FeatherIcon. That fallback is gone: only a lucide-* string, an emoji or symbol glyph, or a Component renders. Any other string renders nothing. No build or type error — the icon silently disappears. A dev-mode console warning names the component, the prop, and the offending value once per (component, prop). Prefix the name with lucide-:

<!-- Before -->
<Button icon="plus" />
<!-- After -->
<Button icon="lucide-plus" />

Same for icon-name strings in Dropdown options:

// Before
const options = [{ label: 'Edit', icon: 'edit' }]

// After
const options = [{ label: 'Edit', icon: 'lucide-pen' }]

Card, ListItem, standalone <Toast> (removed) ​

Three unmaintained wrappers are gone in v1, per ADR-0008 — each shipped @deprecated in code and had zero call sites left across our census of downstream apps.

Card wrapped a title/subtitle/actions layout with a manual loading state. There's no drop-in replacement; rebuild the layout with plain markup, using LoadingText or Skeleton for the loading state:

<!-- Before -->
<Card title="Title" subtitle="Subtitle" :loading="loading">
  <template #actions><Button label="Edit" /></template>
  Content
</Card>

<!-- After -->
<div class="flex flex-col rounded-6 border px-6 py-5">
  <div class="flex items-baseline justify-between">
    <h2 class="text-lg font-semibold">Title</h2>
    <Button label="Edit" />
  </div>
  <p class="mt-1.5 text-ink-gray-6">Subtitle</p>
  <LoadingText v-if="loading" class="mt-4" />
  <div v-else class="mt-4">Content</div>
</div>

ListItem rendered a title/subtitle/actions row. Same story — no drop-in replacement, rebuild with plain markup:

<!-- Before -->
<ListItem title="Title" subtitle="Subtitle">
  <template #actions><Button label="Edit" /></template>
</ListItem>

<!-- After -->
<div class="flex items-center justify-between py-3">
  <div>
    <h3 class="font-medium">Title</h3>
    <p class="text-ink-gray-6">Subtitle</p>
  </div>
  <Button label="Edit" />
</div>

Standalone <Toast> — import { Toast } from 'frappe-ui' and <Toast> fail at the import. This only removes the raw ToastRoot-based component; the imperative API is unaffected and is what you almost certainly want:

<!-- Before -->
<Toast v-model:open="open" message="Saved" type="success" />

<!-- After -->
<script setup>
import { toast } from 'frappe-ui'
toast.success('Saved')
</script>

<ToastProvider> (mount once near your app root) is unchanged. The current API is plain toast() plus toast.success() / toast.error() / toast.warning() / toast.info(). v0's toast.create(), toast.remove() and toast.removeAll() still work, but warn once in dev — move them to toast(...) and toast.dismiss(...).

Tokens ​

Run the v2 token codemod from the app you are migrating:

npx --package frappe-ui@beta tokens-v2 --dry-run .

Review the output, then run it without --dry-run:

npx --package frappe-ui@beta tokens-v2 .

The codemod renames espresso color tokens like bg-surface-white to bg-surface-base, merges static text size + weight class pairs (for example text-base font-medium to text-base-medium), and renames the removed radius aliases (rounded-md → rounded-5, see below). Run it once per codebase; the token migration is not idempotent because some v2 names overlap with v0 names. The radius renames are idempotent and also run on already-migrated codebases.

In every mode, the codemod stays inside the directories you give it. A symlink whose real path leaves the target — a file or a directory — is skipped and listed at the end of the run. Run the codemod on each real package root, so a shared package linked into several apps is migrated once.

After upgrading to [email protected], run the codemod again. Apps that already ran it will only get the typography correction (text-lg → text-md, text-xl → text-lg, ...) and the radius renames. Apps that still have pre-v2 color tokens can pass --force, but review the output carefully because color tokens may double-shift.

Already ran the typography correction too? Pass --radius-only. It performs only the radius renames (safe to repeat) and reports removed tokens — it never touches color or text-size names, so nothing can double-shift.

Unused tokens and utilities removed ​

A pre-1.0.0 audit (#940) removed the token names below — all had zero call sites across frappe-ui and every consumer app. Each is a silent break: the class or --* variable just stops applying, with no build or type error.

text-tiny
text-13xl / text-14xl / text-15xl / text-16xl (and their -medium/-semibold/-bold/-black variants)
shadow-status
--elevation-status
surface-alert-button-default / -info / -success / -warning / -error
ink-alert-button-default / -info / -success / -warning / -error
surface-alpha-gray-2-overlay
surface-alpha-red-1 … surface-alpha-red-7
outline-alpha-red-2 / -3 / -4

The codemod reports only some of these: the dead text sizes, the text-*-black styles, and the two alpha-red families. It has no rule for shadow-status, --elevation-status, the alert-button tokens, or surface-alpha-gray-2-overlay — grep for those five by hand.

If your build used any of these, replace them with the nearest step on the regular scale — e.g. text-16xl → text-12xl, shadow-status → shadow-sm, surface-alert-button-error → surface-red-2 (or whichever variant+theme pairing the design calls for).

Radius aliases removed ​

The named radius aliases are removed in 1.0.0. Numbered tokens are the only radius vocabulary now (ADR-0006). rounded-none and rounded-full are kept.

This is a silent break. The preset replaces Tailwind's borderRadius scale, so an unmigrated rounded-md emits no CSS at all — no build error, no type error, just square corners. Run the codemod, then grep for leftover aliases.

The same map applies to every directional and corner form (rounded-t-lg → rounded-t-6, rounded-tl-sm → rounded-tl-1), to the logical sides (rounded-ss-md → rounded-ss-5, and the same for s, e, se, es, ee), to the bare directional aliases (rounded-t → rounded-t-4), and to variant prefixes (hover:rounded-2xl → hover:rounded-8). Pixel values are identical — the migration changes vocabulary, not rendering.

The codemod handles all of these. One caveat: the bare word rounded is plain English, so the codemod only rewrites it inside quoted strings and @apply rules. A class list inside a multi-line template literal can be missed — grep for bare rounded after running it.

The alias CSS variables go away with the aliases. Hand-written CSS that reads var(--radius-sm) / var(--radius-md) / var(--radius-lg) / var(--radius-xl) / var(--radius-2xl) resolves to nothing — the same silent break. The codemod only rewrites rounded-* classes, so grep for --radius-(sm|md|lg|xl|2xl) and switch to the numbered variables (var(--radius-5) for the old --radius-md, same map as above).

text-*-black styles removed ​

The text-<size>-black / text-p-<size>-black style classes are removed — zero usage anywhere, and the Figma weights behind them were corrupt export data. This is also a silent break: the class stops emitting CSS.

The codemod no longer merges font-extrabold (or font-black) onto a text-*-black class. It flags the pair under "needs manual attention" instead. If you need weight 800, keep font-extrabold; there is no letter-spacing-corrected style class for it.

Ink chromatic scales shift one level ​

The updated espresso v2 tokens shift every chromatic ink scale down one level: the new ink-red-1 is the old ink-red-2, and so on for all 11 chromatic families. The scales now end at -9. ink-gray keeps its own 9-step scale and does not shift. This is a silent break: every ink-<family>-N site renders one shade off after the token update.

Run the codemod once with --ink-shift:

npx --package frappe-ui@beta tokens-v2 --ink-shift .

Run the codemod in the same change as the frappe-ui upgrade that ships the shifted tokens. The upgrade without the codemod renders one shade off. The codemod without the upgrade also renders one shade off. Land both together.

Add --dry-run first to review the renames before they apply:

npx --package frappe-ui@beta tokens-v2 --ink-shift --dry-run .

--ink-shift cannot be combined with --force or --radius-only; the run exits with an error rather than hiding which renames applied. A dry run is not a safety probe either: it only warns when it finds a run-once marker, while a real run refuses outright.

This mode runs only the ink shift — no color renames, no typography, no radius renames. Run it exactly once per codebase. There is no way to detect a prior run from file content (ink-red-5 is a valid name before and after), so a second run double-shifts. To guard against that, --ink-shift takes directory targets only, and a real run writes a .tokens-v2-ink-shift marker file in each target directory. It refuses to run again while a marker exists in the target, an ancestor, or anywhere in the target subtree. The marker is written before the first file rewrite, so an interrupted run refuses to retry instead of double-shifting; restore the tree with git, delete the marker, and re-run. Commit the marker with the migration — on a fresh clone without it the guard is gone, and a teammate's re-run double-shifts. Delete it only to re-run the shift on purpose.

Each marker is created exclusively, so two runs on the same directory cannot both start: the second stops before it rewrites anything. For nested targets (a repo root and one of its subdirectories) the run searches again after it claims its markers, and stops if another run claimed an overlapping tree. Both runs can stop this way. Neither has rewritten a file at that point, so re-run whichever tree is still unshifted.

The marker search follows the same symlink rule as the run: a marker in a linked external package never blocks a target the run would not rewrite. Run the codemod on each real package root directly, so every migrated tree gets its own marker. If the refusal names a marker inside a vendored dependency (for example vendor/frappe-ui/.tokens-v2-ink-shift), that dependency is already shifted — leave its marker alone and target the directories that do not contain it. Pointing at the app root will not help: the search walks the whole subtree, so any ancestor of the vendored copy finds the same marker and refuses again. Target src/ and your other own trees instead.

The old ink-<family>-1 step was white. The new -1 is a light tint, so these sites have no automatic destination. The codemod flags them under "needs manual attention". The usual fix is text-white (or the literal CSS color white in hand-written CSS).

Tight text styles are 1.35 ​

This is a silent break. The text-* styles from text-2xs to text-4xl, with every weight variant, move from line-height 1.15 to 1.35. Each line of text is 0.2em taller: 2.4px at 12px, 2.8px at 14px, 4.8px at 24px. The text-p-* styles and text-5xl and up do not change.

leading-tighter is a new class that sets 1.15, the old default. leading-tight keeps Tailwind's 1.25.

frappe-ui components keep their height. Your own markup can move:

• A row sized by its content grows. A menu, a list of search results or a stack of cards grows by 2.4 to 5px for each row.
• A fixed-height box can clip or push its text off-centre. For example h-4, a min-h-* that the text used to fill, or an offset such as top-[41px] that you measured from the old line.
• Code that reads the value breaks, for example a chart layout that hard-codes 1.15.

Add leading-tighter to single-line chrome in a fixed-height box:

<!-- Before: the row is 28px, a 16.1px line and 12px of padding -->
<button class="flex w-full items-center px-2 py-1.5 text-base">
  {{ item.label }}
</button>

<!-- After: leading-tighter keeps the 16.1px line, so the row stays 28px -->
<button class="flex w-full items-center px-2 py-1.5 text-base leading-tighter">
  {{ item.label }}
</button>

For long prose, use text-p-*: its line height is 1.4 to 1.6.

Packaging and tokens ​

Two loud breaks and three silent ones. Run the codemod first:

npx -p frappe-ui packaging-v1 --dry-run .
npx -p frappe-ui packaging-v1 .

Point it at the project root, not at src: it reads the Vite config and the source that uses icons in the same run. It rewrites the Tailwind preset path, adds lucideIcons: true where the app still needs the resolver, and reports any plugin call it cannot decide.

The preset path ​

The frappe-ui/src/utils/tailwind.config shim is deleted, and no path under frappe-ui/src/... resolves. A loud break: the build stops with Package subpath './src/utils/tailwind.config' is not defined by "exports". The exports map refused that path before this release; the file is now gone as well.

// Before
import preset from 'frappe-ui/src/utils/tailwind.config'
// After
import preset from 'frappe-ui/tailwind'

The same module also exports content, the globs that emit classes inside the package. Tailwind v3 ignores a preset's own content, so spread them into yours. They are already absolute paths, resolved from the installed package, so do not prefix them:

import preset, { content } from 'frappe-ui/tailwind'

export default {
  presets: [preset],
  content: [...content, './index.html', './src/**/*.{vue,js,ts}'],
}

lucideIcons is off ​

frappeui() no longer installs the ~icons resolver, unplugin-auto-import and unplugin-vue-components. A loud break for an ~icons import (Failed to resolve import "~icons/lucide/check") and a quiet one for an auto-imported tag: <LucideCheck /> renders as an unknown element and Vue warns in the console.

// Before
frappeui({ frappeProxy: true })
// After
frappeui({ lucideIcons: true, frappeProxy: true })

Two other ways out, if you would rather not carry the plugins: pass the icon name as a class (<span class="lucide-check size-4" />, drawn by the preset's own icon plugin), or import only the resolver from frappe-ui/vite/lucideIconsPlugin.

The focus ring is an outline ​

The --focus-<name> variables are removed. They held a box-shadow value; --focus-outline-<name> holds the outline form, which does not change the element's size. This is a silent break: box-shadow: var(--focus-red) resolves to nothing and the ring disappears.

/* Before */
.my-input:focus-visible {
  box-shadow: var(--focus-red);
}
/* After */
.my-input:focus-visible {
  outline: var(--focus-outline-red);
}

The names are default, red, green, amber, blue and violet. Each is 2px in light mode and 3px in dark. Grep for --focus- and check every hit carries the outline- segment.

rounded-9, w-wizard and min-w-50 ​

Three silent value changes from the one-scale rewrite:

Everything else on the scale keeps its value, and the scale is now complete: integers 1 to 128 and half steps 0.5 to 19.5. Tailwind 3.4 reads theme('spacing') for width, height, size, minWidth, maxWidth, minHeight and maxHeight, so p-*, m-*, gap-*, w-*, h-*, size-*, min-w-*, max-w-*, min-h-* and max-h-* all read the same numbers.

Dependencies ​

• Install tailwindcss yourself: it is a peer now, >=3.4.2 <4. An install on Tailwind v4 fails.
• vite and vitepress are optional peers, with shiki, @shikijs/transformers and @vue/compiler-dom, which frappe-ui/vitepress imports. Nothing changes unless you import frappe-ui/vite or frappe-ui/vitepress without having them.
• If your app imported ora, slugify, prosemirror-tables, @tailwindcss/line-clamp or a @tiptap/extension-* package through frappe-ui, declare it yourself. They are no longer frappe-ui dependencies.
• In tsconfig.json, keep types: ["vite/client"]. frappe-ui ships TypeScript source, so your compiler checks it, and it reads import.meta.env.

Editor ​

The v0 monolith <TextEditor> (imported from frappe-ui) is replaced by the frappe-ui/editor family: a headless <Editor> you compose with kits (bundled, configurable extension sets) and building-block menus. Everything moves to the frappe-ui/editor subpath; TextEditor and its siblings (TextEditorBubbleMenu, TextEditorFixedMenu, TextEditorFloatingMenu, TextEditorContent, createEditorButton) are removed from top-level frappe-ui in 1.0.0, and so are the v0 extension helpers ImageExtension and createSuggestionExtension with their types SetImageOptions, BaseSuggestionItem and CreateSuggestionExtensionOptions — nothing editor-related is exported from root. See the Editor page for the full API and recipes.

Not migrated yet? All eleven v0 names are parked, unchanged, in frappe-ui/experimental as an interim import path. It is unstable — no deprecation window — and will be removed once consumers migrate:

import {
  TextEditor,
  TextEditorBubbleMenu,
  TextEditorFixedMenu,
  TextEditorFloatingMenu,
  TextEditorContent,
  createEditorButton,
  ImageExtension,
  createSuggestionExtension,
} from 'frappe-ui/experimental'
import type {
  SetImageOptions,
  BaseSuggestionItem,
  CreateSuggestionExtensionOptions,
} from 'frappe-ui/experimental'