Skip to main content

Starwind UI v3.0 is now available! Migration guide

Changelog: Starwind UI 3.6

Starwind UI 3.6 sends less JavaScript, brings the Vue and Svelte betas in line with React, and fixes Combobox, forms, and focus.

BBranden

Starwind UI 3.6 sends less JavaScript: Astro pages load about 9% less, and React components are about 7% smaller on average.

The Vue and Svelte betas now also follow React in how they handle values, events, and props. This release also fixes Combobox, forms, and focus in every framework.

This release has these package versions:

  • starwind (the CLI) 3.6.0
  • @starwind-ui/runtime, @starwind-ui/astro, and @starwind-ui/react 1.5.0
  • @starwind-ui/vue 0.4.0, a public beta
  • @starwind-ui/svelte 0.3.0, a public beta

Smaller Builds

  • When you import one part by name from a React component path, you no longer get the other parts. For example, importing only DialogTitle from @starwind-ui/react/dialog went from about 11 KB to about 0.2 KB with esbuild. A namespace import, such as import { Dialog } from "@starwind-ui/react/dialog", still includes every part.
  • Production React builds no longer include component display names. Development builds keep them, so React DevTools still shows them.
  • Field no longer loads Color Picker code unless the Field holds a Color Picker.
  • A page that imports Field with several controls now loads fewer separate files.
  • Runtime uses shorter internal names in its build. It now publishes source maps, so stack traces and debugger views show the real names.

Field loads more code in one case. Your page may call createField and import no Runtime code for a control inside that Field. Field then loads the code for all ten controls it can hold, about 47 KB gzipped in total. To skip that, import the control’s own entry, such as @starwind-ui/runtime/select. The Astro, React, Vue, and Svelte control components already do this.

Vue and Svelte Now Match React

The Vue and Svelte packages stay in public beta. Their APIs can still change during the 0.x releases.

Svelte values that you pass

Svelte components now follow a value from your state the same way React and Vue do. If you pass a defined value when the component mounts, your state owns that value while the component stays mounted. This applies to open, value, checked, and the other model props on 27 components, such as Dialog, Select, Combobox, and Tabs. A form reset keeps your value.

If you pass undefined at mount, the component keeps its own state. A form reset then returns it to its default.

You may need to change your code here. A one-way prop such as open={open} no longer lets the component change on its own. Use bind:open={open}, or update your state in the change callback. Code that uses bind: keeps working.

Checkbox Group, Toggle Group, Accordion, and Input also follow push() and splice() on a $state array.

Combobox events in the same order

Combobox now sends its events in the same order in Astro, React, Vue, and Svelte. Pressing an item gives the value change, then the input text change with the item-press reason, then the open change. Clearing gives the value change, then the input text change to "" with the clear reason. You can cancel the input text change in every framework.

Vue fixes

  • A Boolean prop that you leave out of a Styled component no longer becomes false. The default of the underlying component applies.
  • v-model now works on Textarea, Native Select, and Input Group Textarea.
  • Textarea and Input Group Textarea keep a v-model value after a form reset, and they accept default-value.
  • Slider.Thumb now accepts inputRef, as it does in React and Svelte.
  • Color Picker with formats and no format now starts on the first listed format. Before, the format selector was blank.
  • Navigation Menu now moves keyboard focus into its content when you use v-model.
  • Tooltip now opens on a native link or span.
  • CarouselNext, CarouselPrevious, and SidebarRail keep your aria-label.
  • Input keeps the caret during a normal edit and puts the old text back when the parent refuses a change.

Svelte fixes

  • Tooltip, Popover, and Navigation Menu triggers now accept a link in child. Use the new TriggerChildPayload type for your snippet.
  • Textarea and Input Group Textarea keep your value after a form reset. Before, the field went blank.
  • A Combobox that gets its props through a spread, such as {...props}, now shows the new label when your state changes value.
  • Color Picker with formats and no format now starts on the first listed format.
  • A bound Slider no longer resets to 0.
  • Tooltip now opens on a native link or span.
  • The Primitive Combobox.Clear no longer adds an English aria-label. Set your own label.

Tooltip and Hover Card in Vue and Svelte also no longer stay hidden when their popup is replaced while open.

Fixes in Every Framework

  • Combobox now closes when focus leaves it. Before, the list stayed open after Tab or Shift+Tab. The close uses the new focus-out reason. Call cancel() in onOpenChange to keep the list open.
  • Every ComboboxClear and every ComboboxTrigger in a Combobox now works. Before, only the first one did.
  • A Navigation Menu panel no longer flashes and closes when you hover a trigger and then click it.
  • Popover, Navigation Menu, and non-modal Dialog no longer pull focus back to their trigger after you move to another control.
  • Triggers on links and spans no longer stay disabled when a framework writes disabled="false".
  • Input no longer writes an unchanged value back into the field. In some browsers this moved the caret or ended an IME composition.
  • Pressing the trigger of an open Select in Safari now closes the list.

A name on a control now wins over the name on its Field. For example, <Field name="fruit"><Select name="own"> submits own. If your server reads the Field name, remove the name from the control.

Astro

  • An attribute that you set, such as role or aria-label, now wins over the component’s own default. Before, the browser kept the component’s value.
  • Dialog, Alert Dialog, and Drawer Trigger and Close parts now accept asChild, so you can use your own button inside them.
  • TooltipTrigger with plain text now renders a button, so keyboard users can focus it.
  • Textarea and InputGroupTextarea now show defaultValue and value in the field.
  • Checkbox and Switch inside a Field now clear when the form resets.
  • Select.Value with its own content and no placeholder now shows that content until a value is chosen.

React

  • Select, Combobox, and Input OTP inside a Field with a name now send their value when the form submits. Select and Combobox in a Field now also call onValueChange, onOpenChange, and onInputValueChange.
  • Select and Combobox now show the selected label when your own component renders the items. If your items load later, a value has no label until someone opens the list and picks an item.
  • Combobox now opens on the first focus of its input, as it does in the other frameworks.
  • Select keeps the label of the parent value after the parent refuses a pick.

CLI

starwind 3.6.0 sets up more projects:

  • starwind init --framework svelte in an Astro project now installs and configures @astrojs/svelte. It picks the version that matches Astro 5, 6, or 7. On Astro 5, this integration needs TypeScript ^5.
  • starwind init works on a new SvelteKit 3 project and on a recent SvelteKit 2 project with no svelte.config file.
  • starwind init now adds the theme script to Vite Vue and Vite Svelte projects, so a saved dark theme applies before the first paint. It also adds the @ alias to Vite Svelte projects.
  • starwind init for Vue on Astro 5 and Astro 6 now installs a matching @astrojs/vue. Before, npm stopped with an ERESOLVE error.
  • On Astro 5 projects with a low declared range, such as "astro": "^5.0.0", the CLI now reads the installed Astro version. Before, astro build could fail.

Work Offline

The new @starwind-ui/offline kit runs the CLI without a network connection. The kit is in beta. Install it once while you are online:

Terminal window
npm install --global @starwind-ui/offline@beta

Then run starwind-offline init or starwind-offline add <component> with the same options as starwind. The kit installs packages through your project’s own package manager (npm, pnpm, or Yarn 2 or later), and your lockfile keeps the public npm registry URLs. Install your project’s own dependencies, such as Astro, before you go offline. The CLI guide lists the supported platforms and limits.

Removed Beta-Only APIs

These APIs existed only in the Vue or Svelte beta. No other framework had them.

Svelte

  • Select no longer exports show, close, or updatePosition. Use bind:open or bind:value.
  • The children snippet on the Alert Dialog, Collapsible, Context Menu, Dialog, Drawer, Menu, Popover, Hover Card, and Tooltip roots no longer receives open. Use bind:open.
  • The Primitive Sidebar.MenuButton no longer takes href. Use its child snippet to render a link. The Styled SidebarMenuButton keeps href.
  • Navigation Menu Popup no longer takes side or align. Set them on Positioner.
  • Menu.Item and Menu.LinkItem render data-close-on-click only when you change the default. Update CSS or tests that read data-close-on-click="true" on a default item.

Vue

The template refs of the Menu, Context Menu, Select, Combobox, and Navigation Menu roots no longer have the open, close, updatePosition, getValue, and setValue methods. They expose only element. Use v-model on the root. For example, put v-model:open="open" on the root, and change menu.value.open() to open.value = true.

Update

Update the CLI-installed components in your project:

Terminal window
npx starwind@latest update --all

The command offers to update @starwind-ui/runtime and the other Starwind packages when they are out of date. Updating can overwrite your local component changes, so commit them first. The CLI guide has the other options.

If something does not work as you expect, open an issue with your setup and a small example.