Migration from v0 ​

This guide moves an existing app onto frappe-ui v1. Work through one component family at a time. Each section starts with a before/after table. For the full list of changes, see the changelog. For the reasons behind each API, see the v1 release specs.

After each pass, grep for the old prop or slot name to find anything you missed, then test the flows you changed. Type-checking does not catch focus changes, slot renames or visual regressions.

What this guide covers ​

Every silent break has a before/after here. A silent break is old code that still runs and still type-checks, but behaves differently. Vue drops an unknown prop or slot without any warning, so these are the changes that reach production. Each one is marked.

Loud breaks are changes your build reports: an import that no longer resolves, or a type that no longer exists. They are listed in the changelog, and appear here only when the replacement needs explaining. If your build already names the file and the line, the changelog is faster to read.

Each change in this guide starts with one of these labels:

Codemods ​

Run the codemod linked from each section. frappe-ui ships ten. The tools report ambiguous dynamic syntax for manual review instead of guessing.

Run each one from the app you are migrating. Where a section gives a --dry-run form, run that first and review the output:

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

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

npx destinations-v1 .

npx overlays-v1 .

npx navigation-v1 .

npx --package frappe-ui@1 shortcuts-v1 --dry-run .
npx --package frappe-ui@1 shortcuts-v1 .

npx --package frappe-ui@1 base-props-v1 --dry-run src
npx --package frappe-ui@1 base-props-v1 src

npx list-v1 .

npx --package frappe-ui@1 editor-v1 --dry-run .
npx --package frappe-ui@1 editor-v1 .

npx -p frappe-ui data-v1 ./src

The commands are written the way each section gives them. The overlays-v1 command is not given elsewhere in this guide; it follows the tool's usage line, overlays-v1 [--dry-run] <dir-or-file...>.

Sections ​

The sections are grouped in the order most apps meet them: first the install and build setup, then components, then data fetching, then the families that only moved.

• Setup — Requirements · Packaging and tokens (Preset path · lucideIcons · Focus ring · Sizing changes · Dependencies) · Tokens · Line height · Family stylesheets · hljs-theme.css and tailwind/tokens.js · frappe-ui/frappe and frappe-ui/drive
• Destinations — Navigation destinations
• 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 — Sidebar · SettingsDialog · Tabs · TabButtons · TabButtons class · App shells and ScrollArea · --mobile-header-height · PageHeaderMobile · Divider
• Keyboard — useShortcut · KeyboardShortcutsModal · The shortcuts codemod · KeyboardShortcut
• Display — Alert · Badge · Icons · Base component props · List family · Tree · Card, ListItem, Toast · Toast legacy object · Toast description
• Editor and charts — Editor · Code editor · Charts
• Data and transport — useDoctype / useList · Writes reject · Data-fetching exports · Errors renamed · HTTP transport and the plugin · beforeSubmit · Composables and directives · Color scheme · pageMetaPlugin
• Removed and parked — Removed and parked components lists every removed component with its replacement, and every parked one.
• 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.
• FAQ

Requirements ​

Node. This is a new minimum, not a raised one. A Node 18 image that built v0 without problems now fails to install.

Tailwind. frappe-ui/tailwind is a v3 preset. frappe-ui declares tailwindcss as a peer dependency, >=3.4.2 <4, so install it yourself; see Dependencies below. A v4 project does not work with the preset. See the Tailwind page.

VueUse. 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. A resolve.dedupe entry for @vueuse/core then collapses them onto whichever copy wins, and that breaks the components that expect the newer one.

Packaging and tokens ​

Two loud breaks and three silent ones, in how frappe-ui is installed and set up in your build.

Codemod: run packaging-v1 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
• reports any plugin call it cannot decide

The preset path ​

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

// 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 for files inside the package that use classes. 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 add a prefix:

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.

• Loud break for an ~icons import: Failed to resolve import "~icons/lucide/check".
• Quiet break for an auto-imported tag: the build passes, <LucideCheck /> renders as an unknown element, and the only sign is a Vue warning in the console.

Codemod: packaging-v1 adds the option where the app still needs it.

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

If you do not want to keep these plugins, there are two other options:

• Pass the icon name as a class: <span class="lucide-check size-4" />. The preset's own icon plugin draws it.
• 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.

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 mode. Grep for --focus- and check that every hit has the outline- part.

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

Silent break. Three values change because the sizing scales were merged into one scale:

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 use the same numbers.

Dependencies ​

• Install tailwindcss yourself: it is a peer dependency now, >=3.4.2 <4. An install on Tailwind v4 fails.
• vite and vitepress are optional peer dependencies, together 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 installed.
• 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 that source reads import.meta.env.

Tokens ​

The Tailwind token names change to the espresso v2 names. Radius aliases, some unused tokens and the text-*-black styles are removed, and the tight text styles get a taller line height.

Running tokens-v2 ​

Codemod: run the v2 token codemod from the app you are migrating. Start with a dry run:

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

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

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

The codemod:

• renames espresso color tokens, for example bg-surface-white to bg-surface-base
• merges static text size + weight class pairs, for example text-base font-medium to text-base-medium
• renames the removed radius aliases (rounded-md → rounded-5, see Radius aliases removed)

Run the token migration once per codebase. It is not idempotent, because some v2 names overlap with v0 names. The radius renames are idempotent, and they also run on codebases that are already migrated.

Symlinks. 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 that a shared package linked into several apps is migrated once.

After upgrading to [email protected], run the codemod again.

• Apps that already ran it get only 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. Review the output carefully, because color tokens can shift twice.
• Already ran the typography correction too? Pass --radius-only. It does only the radius renames (safe to repeat) and reports removed tokens. It never touches color or text-size names, so nothing can shift twice.

Unused tokens and utilities removed ​

An audit before 1.0.0 (#940) removed the token names below. None of them had any call sites in frappe-ui or in any consumer app.

Silent break for each: the class or --* variable 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. For example: text-16xl → text-12xl, shadow-status → shadow-sm, surface-alert-button-error → surface-red-2 (or whichever variant + theme pair the design calls for).

Radius aliases removed ​

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

Silent break. The preset replaces Tailwind's borderRadius scale, so an unmigrated rounded-md emits no CSS at all. There is no build error and no type error, just square corners. Codemod: tokens-v2 handles these. Run it, 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)
• the logical sides (rounded-ss-md → rounded-ss-5, and the same for s, e, se, es, ee)
• the bare directional aliases (rounded-t → rounded-t-4)
• variant prefixes (hover:rounded-2xl → hover:rounded-8)

The pixel values are identical. Only the names change, not the rendering.

Caveat: the bare word rounded is also an English word, so the codemod rewrites it only inside quoted strings and @apply rules. It can miss a class list inside a multi-line template literal. Grep for bare rounded after running it.

CSS variables. The alias CSS variables are removed 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 rewrites only 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, with the same map as above).

text-*-black styles removed ​

The text-<size>-black / text-p-<size>-black style classes are removed. They had no usage anywhere, and the Figma weights behind them were corrupt export data.

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 style class for it with corrected letter spacing.

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.

Silent break: every ink-<family>-N site renders one shade off after the token update.

Codemod: run tokens-v2 once with --ink-shift:

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

Land the codemod and the upgrade in the same change: the change that upgrades to the frappe-ui version with the shifted tokens.

• The upgrade without the codemod renders one shade off.
• The codemod without the upgrade also renders one shade off.

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

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

Flags. --ink-shift cannot be combined with --force or --radius-only. The run exits with an error instead of hiding which renames applied. A dry run is not a safety check either: it only warns when it finds a run-once marker, while a real run refuses.

Run it exactly once per codebase. This mode runs only the ink shift: no color renames, no typography, no radius renames. Nothing in a file shows whether it already ran (ink-red-5 is a valid name before and after), so a second run shifts twice. To guard against that:

• --ink-shift takes directory targets only.
• 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, in an ancestor, or anywhere in the target subtree.
• The marker is written before the first file is rewritten, so an interrupted run refuses to retry instead of shifting twice. To recover, 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 shifts twice. Delete it only when you want to re-run the shift on purpose.

Parallel runs. Each marker is created exclusively, so two runs on the same directory cannot both start: the second one 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.

Linked and vendored packages. The marker search follows the same symlink rule as the run: a marker in a linked external package never blocks a target that 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 does 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 -1 step. The old ink-<family>-1 step was white. The new -1 is a light tint, so these sites have no automatic replacement. The codemod flags them under "needs manual attention". The usual fix is text-white (or the CSS color white in hand-written CSS).

Tight text styles are 1.35 ​

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 its text or push it 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 UI 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.

Family stylesheets (list-style.css / editor-style.css) ​

The manual frappe-ui/list-style.css and frappe-ui/editor-style.css exports are removed. The frappe-ui/list and frappe-ui/editor barrels are now marked as having side effects. So each family's CSS is included in your production build automatically when you import anything from its subpath.

Loud break. The build fails (Missing "./list-style.css" specifier in "frappe-ui" package) until the lines are gone. Delete the manual imports. There is nothing to add back:

/* Before */
@import 'frappe-ui/list-style.css';
@import 'frappe-ui/editor-style.css';
/* After: nothing — the CSS ships with the subpath import */

hljs-theme.css and tailwind/tokens.js (removed) ​

Both subpaths are removed. Loud break for both: the specifier stops resolving.

frappe-ui/tailwind/tokens: new specifier and new names ​

The subpath is back without the .js, but that is not the whole change. Two things change: the specifier, and every name behind it except fontSize. If you only drop the extension, you import names that the module does not export, and the import fails to link. Rewrite the specifier and the import list together.

An earlier version of this guide sent you to the preset. That was wrong. The preset is a Tailwind Config, and its colours, radii and sizes are built inside plugin.js when Tailwind calls the plugin, so you cannot read a value out of it.

// Before
import {
  borderRadius,
  boxShadow,
  fontSize,
  generateCSSVariables,
  generateSemanticColors,
} from 'frappe-ui/tailwind/tokens.js'

// After
import {
  radius,
  shadows,
  fontSize,
  cssVariables,
  semanticColors,
} from 'frappe-ui/tailwind/tokens'

The names changed, and so did the shapes:

Colour values. The old module re-exported colorPalette.js, so its colours carried Tailwind placeholders. A consumer got oklch(L C H / <alpha-value>) from generateColorPalette(), and a color-mix(...) wrapper around calc(<alpha-value> * 100%) from generateSemanticColors(). A colour picker given either one renders an empty swatch. The new exports carry no placeholder.

colors, focusRing, fontFamily, fontWeight, screens, spacing and tracking are exported from the same subpath. See Tailwind Setup.

frappe-ui/frappe and frappe-ui/drive (removed) ​

Both subpaths are removed in v1. frappe-ui is a UI library. The members that know about doctypes, onboarding flows or billing moved to @framework/ui (the ui/ package in the frappe repo).

Loud break for every row: the import path stops resolving.

@framework/ui has frappe-ui as a peer dependency. Add @framework/ui as a dependency if your app does not have it yet, then change the import path:

// Before
import { useTelemetry, TrialBanner } from 'frappe-ui/frappe'

// After
import { useTelemetry, TrialBanner } from '@framework/ui'

Two replacements are supersets of what they replace, so existing call sites work unchanged:

• Link adds redirectable / editable props and redirect / edit emits.
• Filter adds a useFilters composable, parseFilters / serializeFilters, and an operator registry.

The drive components were removed because the drive app already has the live copy of all six. Nothing imported the subpath.

Remove the stale Tailwind glob ​

The frappe/ directory no longer ships, so this line in tailwind.config.js scans nothing. Delete it:

// Delete this line
'./node_modules/frappe-ui/frappe/**/*.{vue,js,ts,jsx,tsx}',

Better: replace the hand-copied list with the content export, which follows the library's source directories for you.

Navigation destinations ​

Component props that take a destination are renamed. Codemod:npx destinations-v1 . migrates 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. (Not covered by the codemod.)

The codemod leaves these alone on purpose. Review them by hand:

• globally registered components
• JavaScript and TypeScript data objects
• render functions
• v-bind="object" spreads

Dialog ​

The options object is flattened into top-level props, and several slots are renamed. See the Dialog component page for the full API.

Props and slots ​

Silent break for most rows of the table. Vue drops an unknown prop or slot with no error. The dialog then renders with no title, no actions, or an empty body. A leftover :disable-outside-click-to-close quietly makes the dialog dismissible.

Loud break for two rows:

• onClick: (close) => close() throws TypeError: close is not a function.
• A template-ref .close() throws the same way.

v-model itself still works, because modelValue is kept as a second binding. But open is the main binding, and it 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, and wrap your app root in <FrappeUIProvider>. These helpers are callback-based: when onConfirm resolves, the dialog closes; when it throws, the dialog stays open.

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. The two choices are now separate, and an icon component is now possible.

<!-- 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. These 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' })

Silent break in production, loud in development. 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 removed (loud in TypeScript).

Coming from v0, the older appearance key is removed the same way. Map it to theme like this:

DialogAction is ImperativeDialogAction for dialog.* ​

Two action types had the same name:

• The component's actions prop takes DialogAction. Its onClick receives { close }.
• The imperative helpers take a different shape. Its onClick receives { close, setError } and is awaited. This one is now 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, the same as in Alert, SidebarCard, Badge and Avatar. Dialog was the last component that spelled it yellow. It already drew that value with the amber tokens, so only the word changes, not the color.

Silent break in JavaScript: yellow is no longer a key in the tone maps, so the icon renders with no tone and nothing throws. TypeScript reports a union error.

A template ref no longer exposes close() ​

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

<!-- 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>

Popover / HoverCard / Tooltip ​

The v0 Popover API is removed in 1.0.0. Nothing is aliased and nothing warns.

Silent break. Vue drops an unknown prop or slot without an error, so a missed call site renders a popover with no trigger, or an empty one. Check every <Popover> in your app.

Changes with nothing to grep for ​

These two changes have no prop name you can search for:

• Panel width. v0 always set the panel's min-width to the trigger's width. v1 does this only when matchTriggerWidth is set. A panel that depended on it now shrinks to its content.
• Portal target. 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 that targets 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. That adds the click handler, keyboard support and aria-expanded.

Remove your own click handler. If you keep it, the popover toggles twice and stays 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, or a drag that must not open it), bind open and accept only closes. Then the trigger's own toggle cannot open the popover without your code knowing:

<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. That is what it already meant on Dropdown, Select, MultiSelect, HoverCard and Sidebar. Only Popover used it for a method.

Silent break: a destructured isOpen becomes undefined, so a class bound to it stops applying with no error. Grep for it.

<!-- 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 no slot props at all. #trigger wires its own click, so the open() method it used to pass had no callers. setOpen is there for code that opens and closes the popover by hand.

Attributes are not inherited ​

Silent break. <Popover class="…"> and <Popover :style="…"> used to land on a wrapper that 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 ​

Panels that open on hover 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 ​

Silent break. The tooltip keeps working, but it points the wrong way, loses its styling, or comes up empty.

arrowClass was documented as the arrow's fill, but it was mostly used to move the bubble's position. offset does that directly.

#default is still the trigger. This is deliberate and will not change.

<!-- 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. Call sites copied the bubble's own classes by hand to get the surface back. #content renders inside the bubble, so you can remove that wrapper:

<!-- 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, for example), 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>

CommandPalette ​

CommandPalette and CommandPaletteItem leave the root export. The family is rebuilt as seven parts that you compose, in frappe-ui/experimental. It stays there, with no stability promise, until gameplan, helpdesk and this site all use it.

Loud break at the import: the root import fails to resolve, so your build names every call site.

// Before
import { CommandPalette, CommandPaletteItem } from 'frappe-ui'

// After
import {
  CommandPalette,
  CommandPaletteInput,
  CommandPaletteList,
  CommandPaletteGroup,
  CommandPaletteItem,
  CommandPaletteEmpty,
  CommandPaletteFooter,
} from 'frappe-ui/experimental'

The groups prop becomes markup ​

groups is removed. Write the rows as parts, so a group renders whatever it needs without a separate component option for each group.

<!-- Before -->
<CommandPalette
  v-model:open="open"
  v-model:query="q"
  :groups="groups"
  @select="onSelect"
/>

<!-- After -->
<CommandPalette v-model:open="open" v-model:query="q" @select="onSelect">
  <CommandPaletteInput placeholder="Search" />

  <CommandPaletteList>
    <CommandPaletteGroup
      v-for="group in groups"
      :key="group.title"
      :label="group.hideTitle ? undefined : group.title"
    >
      <CommandPaletteItem
        v-for="item in group.items"
        :key="item.name"
        :value="item"
        :disabled="item.disabled"
      >
        <template v-if="item.icon" #prefix>
          <span :class="[item.icon, 'mr-3 size-4']" />
        </template>
        {{ item.title }}
        <template v-if="item.description" #suffix>{{ item.description }}</template>
      </CommandPaletteItem>
    </CommandPaletteGroup>
  </CommandPaletteList>

  <CommandPaletteEmpty />
</CommandPalette>

CommandPaletteList is the list itself, and the only part that scrolls. It may contain rows and groups and nothing else, so the input field, the empty state and the footer stay outside it.

select now carries two arguments: the item's value, and the click that picked it. Call event.preventDefault() to keep the palette open.

Filtering is included ​

Behavior change. The old palette filtered nothing; it rendered groups as given. The new one filters against the query by default, so a call site that never filtered starts narrowing its list. Usually that fixes something instead of breaking it.

Set :filterable="false" when a server search already decided what matches, then refetch on update:query yourself. Combobox and MultiSelect use the same prop name.

An item filters on the text of its default slot. #prefix and #suffix are not included, so a shortcut hint at the end of a row is never searched.

Mod+K moves to the caller ​

The palette registered Mod+K itself, with enabled: () => !document.activeElement?.closest('.ProseMirror'). That hardcoded knowledge of the rich-text editor. Both are removed. Register the shortcut in your app, where you know when it should apply:

useKeyboardShortcut({
  combo: 'Mod+K',
  description: 'Open command palette',
  allowInInput: true,
  handler: () => (open.value = true),
})

Keep allowInInput: true. The old palette set it, and useKeyboardShortcut defaults it to false. If you leave it out, Mod+K stops working as soon as a field has focus.

If you are on 1.0.0-beta or older ​

Two earlier renames are part of the same move: show became open, and searchQuery became query.

Silent break for both: Vue accepts the unknown prop, so the palette never opens and your query binding never updates. Suite's SheetEditor still binds v-model:show and v-model:searchQuery, so its palette does not open today.

DatePicker / TimePicker family ​

Covers DatePicker, DateRangePicker, DateTimePicker and TimePicker. They share the same trigger props and slots. Every removed prop and slot below is deleted, not aliased.

Silent break for most of this table. Nothing warns at the tag. An old prop name that is no longer in the component's types lands as an inert extra attribute instead of throwing. For the min/max aliases, the constraint just stops being enforced. #target is the one slot case: content in a leftover <template #target> stops rendering without an error. TypeScript callers get a compile error instead. grep for each old name after upgrading.

@change still fires alongside @update:modelValue. It is not deprecated and does not need replacing.

Trigger slot props ​

#trigger, #prefix, #suffix and #actions receive open, setOpen, close and disabled, alongside their picker-specific fields. TimePicker's #suffix receives the same. 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. These apply even if you do not touch your code:

• DateRangePicker emits a [from, to] tuple. Update handlers that called .split(',') on the value.
• Silent break: DateRangePicker.modelValue is string[] on the way in too. A stored v0 "from,to" string is read by position, so the picker opens with nothing selected and no error. Convert stored values with .split(',') before binding.
• DateTimePicker no longer closes by itself when a date is clicked. Close it from @update:modelValue, or add an Apply button in #actions.
• The popover footer and the automatic Clear button are removed. If you relied on them, render an explicit Clear button inside #actions.
• 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".
• Loud break: useDatePicker and its helpers (getDate, getDatesAfter, getDaysInMonth, isLeapYear) are deleted, so the import fails. Nothing in the picker components used them. Drop the import.

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

update:open replaces both open and close. Its payload is the new open state. input-invalid and invalid-change are removed with nothing in their place: typed text that does not parse reverts to the last valid value, and the user sees that.

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

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

Silent break in JavaScript: a leftover @open 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 allowed a one-element array. 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 } on the template ref. Before, they exposed only open(). open() does nothing 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. Useful if you style or test the pickers:

• The chevron carries data-slot="chevron".
• The <input> carries role="combobox", aria-haspopup (dialog on the date pickers, listbox on TimePicker) and aria-expanded.
• The <input> keeps data-slot="control". data-slot="trigger" is used only for the selection family's box.

MonthPicker ​

Loud break: MonthPicker is deleted, so the import fails.

Its model was one string that held both parts, "<Month> <Year>" (for example "January 2026"). A popover switched between a month grid and a year grid to write it. Nothing in v1 does the same, so pick the replacement that matches what your code reads from 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 these components together. They share an option shape and slot names, and most apps use more than one of them. The removed props, option keys and slot props are deleted, not aliased. Most of them fail without an error; each subsection says which.

Changes shared by all of them ​

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

Select ​

Silent break: the empty value. Select emitted undefined and Combobox emitted null, so two single-value components gave two different answers for "nothing selected". Both emit 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 consumers iterate over an empty array.
• An empty string is still a real value, so a "None" row with value: '' is returned unchanged.

Neither component emits anything on mount. A model that starts as undefined stays undefined until the user picks or clears an option. Both components read undefined as "nothing selected", so the placeholder renders either way. Initialize the ref with null if you compare the value, send it to the server, or watch it for the empty case.

Additive: 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 ​

See Custom rows, Custom options on Combobox and If you used allowCustomValue for the rows that need code changes.

MultiSelect ​

Dropdown and ContextMenu ​

Silent break in plain JavaScript apps, for all three behavior removals below. 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 removed from DropdownProps.
• A development-mode console warning also fires when placement, items or component reaches the menu at runtime.

These changes apply the same way to ContextMenu, which shares the option shape. ContextMenuComponentOption is removed together with DropdownComponentOption.

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

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

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

2. A { group, items } entry disappears. The group resolves to zero options and is dropped. The rest of the menu stays intact:

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

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

3. A component: row renders as a plain action row using its label. For most of these rows, the label is empty:

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

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

Custom rows ​

Three ways to hand the whole row to your own code are removed:

• Select and MultiSelect lost the #option slot.
• Combobox and MultiSelect lost render and slotName.

All three are replaced by region slots on a row that the component renders.

<!-- 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 now rendered from option.icon automatically. In the common case you need no slot: set icon and drop both templates.

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

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

To replace the whole row, you can still use slots.item or the #item template slot.

Custom options on Combobox ​

Two keys on the custom option object are renamed: slotName → slot, and searchTerm → query.

// 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 that the row renders into is renamed too. #create-new becomes #item-create-new. 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 removed. It could not do anything a custom row cannot do, and its row was fixed: you could not change the label, add an icon, or control when it appears.

Build the row yourself. 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 anyway (the trigger shows 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 from a search endpoint, this 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 go back to the library component.

For the removed Autocomplete, see Autocomplete (removed).

Autocomplete (removed) ​

Autocomplete is removed in v1. It handled single and multiple selection in one component, through the multiple boolean. v1 splits them: Combobox for single selection, MultiSelect for multiple.

Loud break at the import, so your build lists every call site. Silent break for three things inside those call sites; each has a before/after below:

• the v-model payload
• the group key
• the open slot prop, which was a function and is now a boolean

Search your codebase:

grep -rln '<Autocomplete\b' src --include='*.vue'   # find usages
grep -rln ':multiple' src --include='*.vue'         # these become MultiSelect
grep -rn 'items:' src --include='*.vue'             # grouped options — see below

The v-model payload inverts ​

Silent break. Autocomplete took and emitted the whole option object. Both replacements use the value only as the model: Combobox is string | number | null, and MultiSelect is (string | number)[]. Code that reads country.value from the model gets undefined instead of a type error, because the model was loosely typed.

<!-- Before -->
<Autocomplete v-model="country" :options="countries" @change="onChange" />
<!-- country === { label: 'India', value: 'in' } -->

<!-- After -->
<Combobox
  v-model="country"
  :options="countries"
  @update:model-value="onChange"
/>
<!-- country === 'in' -->

Do you still need the whole option, for its description, an id field, or anything else beyond the value? Listen to @update:selectedOption, which carries it:

<Combobox
  v-model="country"
  :options="countries"
  @update:selected-option="(option) => (label = option?.label ?? '')"
/>

Grouped options: items → options ​

The key that holds a group's children is now options, the same as the top-level prop.

• Combobox and MultiSelect throw and name the group if they find the old key. So you find this the first time the picker opens, but only then, not at build time.
• Dropdown and ContextMenu share the rename, but fail differently: the group is dropped without an error (see Dropdown and ContextMenu).

<!-- Before -->
<Autocomplete :options="[{ group: 'Asia', items: [india, japan] }]" />

<!-- After -->
<Combobox :options="[{ group: 'Asia', options: [india, japan] }]" />

#target → #trigger, and drop the click handler ​

The slot is renamed, and the wiring inside it changes. Autocomplete gave #target a togglePopover function that you had to call yourself. Combobox and MultiSelect attach the open toggle to the #trigger element for you.

So the handler is not just unnecessary. A togglePopover() kept through the rename throws togglePopover is not a function on every click. The popover still opens, because the component's own handler already ran. So it looks like it works, with extra errors, until someone looks at the console.

<!-- Before -->
<Autocomplete :options="fields">
  <template #target="{ togglePopover }">
    <Button label="Add filter" @click="togglePopover()" />
  </template>
</Autocomplete>

<!-- After -->
<Combobox :options="fields">
  <template #trigger>
    <Button label="Add filter" />
  </template>
</Combobox>

Silent break: open changed from a function to a boolean. On #target it was the function that opened the popover. So anything that read it as a value (v-if="open", :class="{ 'rotate-180': open }") was reading a function object, which is always truthy. On #trigger it is the real open state, so those expressions now do what they always appeared to do.

• Combobox's #trigger receives { open, disabled, query, selectedOption, displayValue, clear, setOpen, close }.
• MultiSelect's #trigger receives { open, disabled, query, selectedOptions, clear, setOpen, close }: plural, and with no displayValue.

Use setOpen for a trigger that has to open the popover from somewhere other than its own click.

The trigger shape changed — pass trigger="button" to keep v0's ​

Autocomplete rendered a button that showed the selection, with the search box inside the popover. Combobox defaults to trigger="input": the trigger is the search field. Pass trigger="button" to keep the old shape.

FormControl type="autocomplete" (removed) ​

Silent break. FormControl picks a component based on type. With the autocomplete case removed, the type falls through to TextInput and is still passed on as an HTML input type. The result is <input type="autocomplete">, which every browser renders as a plain text box: the picker becomes a text field.

• No runtime error, and no build error in plain JavaScript.
• TypeScript callers get a build error, because 'autocomplete' is no longer in the type union.
• A development-only console.error names it.

<!-- Before -->
<FormControl type="autocomplete" :options="countries" v-model="country" />
<!-- country === { label: 'India', value: 'in' } -->

<!-- After -->
<FormControl type="combobox" :options="countries" v-model="country" />
<!-- country === 'in' -->

The v-model payload inverts here too, for the same reason as in Autocomplete. Or use the standalone Combobox, which exposes the full set of props and slots without the wrapper.

Inputs ​

Covers TextInput, Textarea, Password, Checkbox, Switch, Rating and Slider. They all share the same labeling props (label / description / error / required).

Removed props and events ​

Silent break. Rating :rating_from, Rating :readonly, Switch@change, Switch.labelClasses and Checkbox.padding are removed, not aliased. The old names are ignored without an error:

• a Rating with :rating_from="10" renders 5 stars
• a :readonly Rating becomes interactive
• a Switch @change handler never fires
• labelClasses and Checkbox.padding stop styling anything

Nothing breaks at build time, so grep for these names when you upgrade.

<Input> is removed ​

Loud break when you import it: the import fails, so importing call sites break at build time.

Silent break when you register components globally: there is no import error. The tag fails to resolve and renders nothing. Only development builds show a "Failed to resolve component" warning. Grep for the tag, not the import: grep -rn '<Input\b' src.

Slider has no default aria-label ​

Slider no longer hardcodes aria-label="Volume". Pass label explicitly so screen readers announce the control correctly.

CircularProgressBar is removed ​

Loud break: CircularProgressBar is deleted, so the import fails. Use Progress for a linear bar, or draw the arc yourself. v1 has no circular variant. If you need the circular form, you can copy the v0 component into your app.

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. It was a font override with 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 not affected. <Dialog size="xl"> and <Avatar size="xl"> still work.

Silent break in JavaScript, warned in development. A leftover size="xl" no longer loses the size styles. Every input size lookup now falls back to that component's default (sm for the input family) and warns once in development:

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

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

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

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

Rendering change. Nothing to change in your source. Labels, descriptions and Textarea text are a fixed 13px. Labels and descriptions are ink-gray-6.

The two label components used to render different sizes. InputLabel, which FormControl renders through, was a fixed 14px. FormLabel was 12px or 14px depending on size. Both are 13px now, so a FormLabel and a TextInput label match.

Textarea size still exists and still has an effect: it changes padding, corner radius and the minimum height. It no longer changes the text size. The single-line input heights do not set a Textarea height, so a lg Textarea is a larger box with the same 13px text.

The Textarea value colour is unchanged.

FormLabel — size prop removed ​

With the label size fixed at 13px, FormLabel's size prop had no effect, so it is removed instead of kept as a no-op.

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

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

Silent break in JavaScript, loud in TypeScript. 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 got 14px. You now get 13px.
• If you relied on the sm default, you got 12px. You now get 13px.

Either way the label ends up at the standard size. Usually you should delete the attribute and accept the new size. To keep a different size, style the label yourself.

Password — value prop removed ​

value was a deprecated second way to set the password. It set v-model once on mount. It is removed.

Silent break. :value now falls through as a plain HTML attribute on the native <input> instead of setting 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 returned { el } on the template ref: a raw ref to the native element. They now return { focus, inputElement }:

• Call focus(options?) to move keyboard focus.
• Read inputElement for the native element itself. It is a computed, so it cannot be reassigned.

Password gains the same pair. It exposed nothing before.

Fails at runtime, not 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 other inputs.

focus() is on every input ​

Additive. Checkbox, Switch, Slider, RadioGroup, Rating and FormControl expose focus() too. They exposed nothing before. The shape is declared once as the exported InputExposed type, 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 the control that its type resolved to.

Focus lands on the element that Tab reaches, not on the container:

• Slider focuses the thumb.
• RadioGroup focuses the selected option, or the first enabled one when nothing is selected.
• Rating focuses the selected star, or the first star when the value is empty. In half-star mode 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.

Silent break in four components:

Check two things.

1. A listener now fires once, from the control:

   vue

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

2. A CSS rule written against the wrapper no longer matches a data-* attribute 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 worked this way 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 break. No codemod. A codemod cannot find a prop that is not there. Adding size="md" to every <Rating> in an app to keep 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 ​

These slots used to be dropped. If you passed either slot to Duration, it now renders. Check that it does not repeat a label or description prop that 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.

FormControl type="date" and type="time" render the pickers ​

Behavior change. In v0, type="date" and type="time" fell through to TextInput and rendered the browser's native date and time inputs. They now render DatePicker and TimePicker. The value format stays the same (YYYY-MM-DD and HH:mm), but the control looks and behaves like the pickers.

To keep a native input, use TextInput directly, or type="datetime-local", which still renders a native input:

<!-- Before: a native date input -->
<FormControl type="date" label="Due" v-model="due" />

<!-- After: keep the native input -->
<TextInput type="date" label="Due" v-model="due" />

Additive: FormControl also takes type="daterange" and type="datetime", which render DateRangePicker and DateTimePicker.

data-slot="label" on FormLabel ​

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

Input types the root publishes ​

Additive exports:

• 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 pass one to formatter, disabledDate and the setter slot props, so the type has to be importable.
• DateRangeValue — both sides of DateRangePicker's v-model.
• InputLabelingProps — for a wrapper that forwards label / description / error / required.

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

Emit types. SelectEmits, ComboboxEmits and MultiSelectEmits no longer redeclare the model events that defineModel already declares. RadioGroupEmits says RadioValue | undefined, which is the value an unbound group starts with. A handler typed against the old shapes still compiles. Type a model handler from 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 was reworked in 1.0.0: it is written in TypeScript, takes flat props, and gets a security fix to the upload default it shares with useFileUpload / FileUploadHandler.

Uploads default to private ​

Silent break. useFileUpload() and FileUploadHandler now treat an upload with no stated private / is_private as private, not public.

Coming from v0, FileUploader changes with them. It had no private prop at all and used the public default. It has uploaded private by default since v1.0.0-beta.21, so only upgrades from before beta.21 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 to requests with no session (an avatar in an email digest, an image on a public page), check every call that omits private / is_private before upgrading. A file that becomes private returns 403 to a request with no session, instead of the image.

Uploads reject an UploadError ​

upload, useFileUpload and FileUploadHandler reject with an exported UploadError instead of a plain Error. state.error has that type too.

Check error.kind ('file-size' | 'network' | 'server' | 'abort') instead of 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 pending when the request aborts. It rejects, like the other two.

An aborted upload rejects an UploadError, not a DOMException ​

Silent break. upload() and useFileUpload() take an options.signal.

• Before: when that signal fired, they rejected with new DOMException('Upload cancelled', 'AbortError').
• After: they 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 uses either of those to tell a cancel from a failure stops matching, so a cancelled upload is shown 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 both private and is_private for the same setting, and private won. Only private is left, and it is a boolean.

Silent break in JavaScript, loud in TypeScript. In JavaScript, an is_private you still pass is ignored and the upload falls back to the private default. 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 that the server returns is unchanged.

uploadArgs → flat props ​

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

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

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

Silent break. uploadArgs is no longer a known prop, so Vue passes it through as an inert HTML attribute on the root element. Nothing throws; the options it carried just stop applying. Together with the new private default above, a uploadArgs="{ private: false }" override that used to make an upload public now uploads it as private. 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, because no measured use of them on the component was found. Use useFileUpload() directly for those.

Template ref — inputRef removed ​

FileUploader returns nothing through a template ref, per ADR-0012. inputRef() (a function, despite the name) is removed with nothing in its place. The openFileSelector slot prop already does 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 turned into a message string. Validation failures (a validateFile prop that returns an Error) were not, so error could also be an Error object. Both paths now give a message string.

<!-- 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>

Silent break: a slot that only ever used error.message (expecting the Error shape) now renders undefined instead of the validation message.

Behavior change: 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 now also receives validation rejections, alongside upload errors.

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

Loud break: fileToBase64 is no longer exported from frappe-ui, so the import fails at build time. No external call sites were found during the v1 sweep. To get a file's base64 representation yourself, use a few lines of FileReader.readAsDataURL.

The size-limit helpers (formatBytes, getMaxFileSize, fileSizeLimitMessage) were exported only during the 1.0.0 betas, and are internal now.

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.

Silent break for every removal here. A removed prop (header, sections, items, isActive) becomes a fall-through attribute on the component's root element. Content passed to the removed #sidebar-item slot is discarded. There is no build error, no type error and no warning; the sidebar renders as an empty frame. After upgrading, grep for :header=, :sections=, :items=, #sidebar-item and isActive on these five components.

Codemod: destinations-v1 renames SidebarItem.to to route; see Navigation destinations. navigation-v1 renames SidebarRailItem variant="tile" to variant="subtle".

<!-- 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 adds any padding. Your app does that now. See the Collapse section of the component page for how the parts fit together.

SettingsDialog ​

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

Silent break: Vue accepts the unknown modelValue prop with no error, so the dialog 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. Unlike Dialog, SettingsDialog does not keep the old unnamed v-model binding. open is the only way to control visibility.

shortcut → keyboardShortcut ​

Replace shortcut with keyboardShortcut. It defaults to "Mod+Shift+,", and false turns the registration off.

Codemod: navigation-v1 removes bare and statically true shortcut props, because the new default keeps their behavior. It converts static false values. It reports dynamic boolean expressions, so you can decide by hand between a combo and false.

Tabs ​

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

Codemod: run npx navigation-v1 . for the current active slot-prop and state names on TabButtons and Tabs. The larger rewrite from v0 Tabs to the composed family is still 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 instead of waiting for the build to tell you.

Silent break for the slot rows: an unknown slot name renders nothing and nothing throws. iconRight is silent too: the icon stops rendering and nothing throws.

<!-- 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. TabList now has all the variants that TabButtons has: underline, subtle, ghost, browser-tab.

Scrolling ​

v0 set layout classes by default:

• the root was flex flex-1 overflow-hidden flex-col
• the tablist was overflow-x-auto
• every panel was flex flex-col overflow-auto

v1 sets none of them, because they broke layouts as often as they helped. A Tabs that always grows to fill its parent is wrong everywhere the tabs are not the whole screen.

Silent break. Nothing throws. Inside a container with a fixed height, the panel stops scrolling and overflows instead. Check any call site that relied on these defaults.

In composed mode your app renders 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 you cannot add classes to the generated elements, so target 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: it is a value input, not a panel switcher. Its prop and type names now match the Tabs family. See the TabButtons component page for the full API.

Silent break for every prop rename here. An unknown prop lands in $attrs and is spread onto the radiogroup root. A TabButtons still on :buttons renders an empty track with no build error, type error or warning.

No codemod renames these props. destinations-v1 does not touch TabButtons, and navigation-v1 only renames the checked slot prop to active. Grep for :buttons, type=, direction=, hideLabel, tooltip, and non-string labels in option data.

TabButtons no longer wraps Button, which is why the Button props above stop working. Each tab is a native <button>, an <a href> or a <RouterLink> that renders a Pill. route and href on an option still work: an option with route renders a <RouterLink>, and an option with href renders an <a href target="_blank">.

For the class on an option, see TabButtons: class on an option → data-value.

TabButtons: class on an option → data-value ​

Silent break in JavaScript: class on a TabButton option object no longer applies. Nothing warns and nothing fails; the tab just loses its styling. Style the tab from CSS through the new data-value hook instead.

<!-- Before -->
<script setup>
const tabs = [
  { label: 'Open', value: 'open', class: 'text-red-600 font-bold' },
  { label: 'Closed', value: 'closed' },
]
</script>

<template>
  <TabButtons :buttons="tabs" v-model="tab" />
</template>

<!-- After -->
<script setup>
const tabs = [
  { label: 'Open', value: 'open' },
  { label: 'Closed', value: 'closed' },
]
</script>

<template>
  <TabButtons class="my-tabs" :options="tabs" v-model="tab" />
</template>

<style scoped>
.my-tabs :deep([data-slot='tab-button'][data-value='open']) {
  color: var(--ink-red-3);
  font-weight: 600;
}
</style>

Two related names are removed with it:

• Loud break: NativeButtonClass is no longer exported. The import fails.
• customClass is removed from the #prefix and #suffix slot props. Destructuring it fails. Silent break if you spread it: it gives nothing.

The composed Tabs family needs no change. There you write the <TabTrigger> yourself, so a class goes on the element directly.

App shells and ScrollArea ​

Two exports are removed, useShellScrolled needs a threshold, and pages now read the shell they are inside.

ScrollBar is no longer exported ​

Loud break: import { ScrollBar } from 'frappe-ui' fails at build time. There is no replacement. ScrollArea draws its own scrollbars, and ScrollBar only ever worked inside reka-ui's ScrollAreaRoot, which frappe-ui does not export. Use ScrollArea with orientation:

<!-- After -->
<ScrollArea orientation="both">
  <WideTable />
</ScrollArea>

orientation="both" renders one scrollbar per axis. ScrollBarProps is removed with the component.

useSheetDrag is no longer exported ​

Loud break: useSheetDrag, UseSheetDrag and UseSheetDragOptions leave the root. Both imports fail.

BottomSheet still uses the composable internally and is unchanged, so an app that renders BottomSheet has nothing to do. There is no standalone replacement in 1.0.0: the drag thresholds are fixed values tuned for that one component. It can come back when a second component needs it.

useShellScrolled needs a threshold ​

threshold is now required, in pixels.

// Before — 200px by default
const scrolled = useShellScrolled()

// After
const scrolled = useShellScrolled({ threshold: 12 })

Loud in TypeScript, silent in JavaScript. A call with no argument is a type error, so the build catches it. At runtime it warns in development and stays false.

The old 200px default suited a long document and nothing else. A header border that appears 200px late looks like a bug, not like a missing argument.

A page reads the shell it is inside ​

No code change. useShellScrolled(), and a PageHeader teleporting to its target, now use the nearest enclosing shell first. They fall back to the shellScrollContainer registry only when there is no shell above them.

This changes what you see only while two shells are mounted at once: during a desktop-to-mobile switch, or in a test that mounts both. Before, both answers came from the registry, which returns the shell that mounted most recently, so a header could teleport into the wrong frame.

shellScrollContainer itself is unchanged. It is still the way to reach the scroll element from a router scrollBehavior or any other code outside a component.

DesktopShell takes :scroll="false" ​

Additive. New prop, default true, nothing to migrate. Pass false for a layout whose panes handle their own overflow, instead of working against the shell's page scroll:

<!-- Before -->
<DesktopShell>
  <div class="absolute inset-0 flex h-[calc(100vh-3rem)]">…</div>
</DesktopShell>

<!-- After -->
<DesktopShell :scroll="false">
  <div class="flex min-h-0 flex-1">…</div>
</DesktopShell>

With :scroll="false" the shell has no scroll element, so shellScrollContainer is null and useShellScrolled() stays false. Read the pane's own ScrollArea instead.

Shell slot names stay split ​

No code change. DesktopShell keeps #rail and #sidebar. MobileShell keeps #nav. The names describe regions, not components. The two frames have different regions, so there is no shared name to move to.

--mobile-header-height is removed ​

Silent break. PageHeaderMobile is 52px tall, fixed. It no longer reads --mobile-header-height, so setting that variable does nothing to the library header. Delete the declaration, or keep it if your own CSS reads it; the name belongs to your app now.

There is no replacement hook. For a header of another height, use PageHeaderBase with your own class:

<PageHeaderBase class="flex h-16 items-center border-b px-3">
  <MyToolbar />
</PageHeaderBase>

PageHeaderMobile family: slot names ​

PageHeaderMobile's #left/#right and PageHeaderMobileTitle's #icon are renamed to the shared #prefix/#suffix slot names (see the slot naming rule, P6, in PHILOSOPHY.md).

Silent break: Vue drops content passed to an unknown slot name with no error or warning. The back button, the title icon or the trailing action just stops rendering.

<!-- Before -->
<PageHeaderMobile title="Space">
  <template #left><BackButton /></template>
  <template #right><Button icon="lucide-more-horizontal" /></template>
</PageHeaderMobile>
<PageHeaderMobileTitle title="Space">
  <template #icon><SpaceIcon /></template>
</PageHeaderMobileTitle>

<!-- After -->
<PageHeaderMobile title="Space">
  <template #prefix><BackButton /></template>
  <template #suffix><Button icon="lucide-more-horizontal" /></template>
</PageHeaderMobile>
<PageHeaderMobileTitle title="Space">
  <template #prefix><SpaceIcon /></template>
</PageHeaderMobileTitle>

Grep for #left, #right and #icon on these two components only. Other components (for example ListView's footer) have their own, unrelated #left/#right slots, which are not affected.

FrappeUIProviderProps is deleted ​

The type was exported but never connected to the component, so it described props that FrappeUIProvider did not accept. It is removed in 1.0.0 with no replacement.

Loud break: import type { FrappeUIProviderProps } from 'frappe-ui' fails the type-check. FrappeUIProvider itself is unchanged and still exported.

Divider ​