Migrating to v3

Version 3 drops the styled-jsx runtime: every component now ships plain, static CSS instead of injecting <style> tags at render time. This page lists what changes and what to do about it. The documentation of v2 stays available at v2.bolio-ui.com.

Version 2 was only published as alphas, so most projects come from 1.x or from a v2 alpha. Coming from 1.x, read the migration guide to v2 first, then this page. Install v3 with:

pnpm add @bolio-ui/core

Breaking changes

Import the stylesheet once

Styling used to be injected by styled-jsx on every render. Now it ships as a real .css file, so every app needs one import, once, anywhere before the components render:

import '@bolio-ui/core/styles.css'

Without it, components render unstyled. Add it next to your other top-level imports (pages/_app.js, app/layout.js, src/main.tsx, and so on). See Getting Started for the setup of each router and framework.

StyledJsxRegistry and @bolio-ui/core/next are gone

The App Router no longer needs a styles registry, because nothing is rendered into the HTML at request time anymore. Remove the wrapper:

// v2: app/layout.js
import { BolioUIProvider, CssBaseline } from '@bolio-ui/core'
import { StyledJsxRegistry } from '@bolio-ui/core/next'

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <StyledJsxRegistry>
          <BolioUIProvider>
            <CssBaseline />
            {children}
          </BolioUIProvider>
        </StyledJsxRegistry>
      </body>
    </html>
  )
}

// v3: no registry, just the stylesheet import
import '@bolio-ui/core/styles.css'
import { BolioUIProvider, CssBaseline } from '@bolio-ui/core'

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <BolioUIProvider>
          <CssBaseline />
          {children}
        </BolioUIProvider>
      </body>
    </html>
  )
}

A custom server needs nothing beyond serving the stylesheet (or letting your bundler include it) and rendering the app normally: no registry to collect styles from.

styled-jsx is no longer a dependency

The package does not depend on styled-jsx anymore. If nothing else in your app uses it, you can remove it too.

Package entry points

@bolio-ui/core/next was removed from the exports map. These paths work:

Other paths are no longer resolved.

Rating was rebuilt

The old Rating changed its value on hover and then locked on click. Now the value only changes on click or with the arrow keys, and hover shows a preview.

• • onValueChange is now onChange.
• • locked and onLockedChange are gone. Use readOnly or disabled.
• • initialValue now defaults to 0, not 1.
• • The default color is the warning color, not gray.
• • The types RatingCount and RatingValue are gone: count and value are plain numbers.
• • New props: precision, variant, emptyIcon, clearable, highlightSelectedOnly, onHoverChange and getLabel.

Changes in behavior

• • CSS specificity: every component's styles are now wrapped in a CSS @layer, all of them below any unlayered CSS you write. A plain, unlayered selector in your own stylesheet always wins over a component's default style now, with no need for !important or extra specificity.
• • Class names: internal class names generated by CSS Modules (a hash like Button-module_root__a1b2c) replace the old styled-jsx hash. Neither was ever meant to be targeted directly; use the documented props and CSS custom properties instead.
• • Box sizing: CssBaseline now sets box-sizing: border-box on the page, and every element inherits it. A width or a height now includes the padding and the border. If your own styles assumed content-box, check the elements that have both a size and a border or padding.
• • Collapse: the title is now a heading with a native button inside, in place of a div with role="button". A selector that targeted that div needs to change. Collapse.Group also moves the focus between the titles with the arrow keys, Home and End.
• • Select: the dropdown and its options take the colors of the field, so they follow its type and variant, in place of the fixed gray.
• • Dropdown: Menu, Select, Popover and the other dropdowns open upwards when there is not enough room below. A Menu no longer scrolls the page when it opens.
• • Native controls follow the theme: CssBaseline sets color-scheme on the page, so the clock of a time field, the scrollbars and the pickers of the browser are drawn for a dark page on the dark theme.

New components

These are in v3 and were not in 2.0.0-alpha.2, or in 1.x. Nothing was removed.

• • Carousel, Color Input and Color Picker
• • Command, Context Menu and DateRangePicker
• • Dropzone, Empty State and Image Zoom
• • Marquee, Pin Input and Segmented Control
• • Splitter, Stat and Tags Input
• • Timeline, Tour and Tree
• • Alert, Chip, Mention and Toolbar

Existing components also got new props: Collapse has visible, onVisibleChange and disabled, Calendar has numberOfMonths, and Table has sortable columns (sortable and sorter), sort, selectable, rowKey and selectedKeys.

Checklist

1. Install @bolio-ui/core 3.0.0 or later.
2. Add import '@bolio-ui/core/styles.css' once, near your other top-level imports.
3. Remove StyledJsxRegistry and the @bolio-ui/core/next import from your App Router layout, if you had one.
4. Remove styled-jsx from your own dependencies if nothing else in your app uses it.
5. Search your own CSS for selectors that relied on beating a component's specificity; they may no longer need !important.