Once UI 1.4 migration guide: The breakpoint object

Upgrade your app to Once UI 1.4 in 5 minutes.

Updated 7 days ago

Once UI 1.4 is here with new components, improved component APIs and long-awaited features. Here's what you need to do to upgrade your project.

The LayoutProvider Context

This context is required for the updated Flex and Grid components. Wrap your app's children with the LayoutProvider component in your layout.tsx or Providers.tsx. It lets you override the default breakpoints, but be aware that the overrides only affect runtime logic (layout shifts) and not utility classes (position, styling, etc.). Use the override feature with caution, since it's still a beta feature.

The Breakpoint Object

One of the most important features of the new release is the breakpoint object of the Flex and Grid components that replaces tabletDirection, mobileDirection, tabletColumns, mobileColumns, hide and show props, and provides additional functionalities for overriding default styles at different breakpoints. Let's see them in action through a few examples!

The new, object-based approach supports for an additional xs (480px by default) and l (1440px by default) range with xl standing for everything above 1440px. The property adds a utility class at page load to prevent layout shifts, and then removes the element from the DOM to optimize performance. Legacy syntax: New syntax:

There's only a single, hide prop for managing visibility at different breakpoints. It works similar to the max-width CSS breakpoint property, meaning that the declaration affects all smaller breakpoint too, if not specified otherwise. Legacy syntax: New syntax:

Grid columns can also be overriden with the new breakpoint object. Legacy syntax: New syntax:

New features

You can override most display props with the new breakpoint object. Here's a list of what's currently supported: direction, horizontal, vertical and position. Also notice how top is not set in the above example, since it will default to 0 if not specified when using sticky position. You can set inline styles for different breakpoints, which will be resolved at runtime with a very short delay. It works well for smaller adjustments, especially when the element is hidden at a specific breakpoint, like a mobile menu. We split the Flex and Grid components into client and server counterparts, so whenever you use them, they will automatically detect if client functionality is needed and only render with the use client directive when it's actually needed.

Simplified Alignment

The horizontal and vertical alignment values for the Flex are now accessible with the following shortened syntax:

Legacy	New
`space-between`	`between`
`space-around`	`around`
`space-evenly`	`even`

The new properties are shorter and are more consistent with the existing start and end values.

Migration

Using batch find and replace is generally safe for these updates.

Legacy	New
`tabletDirection="column"`	`m={{direction:"column"}}`
`mobileDirection="column"`	`s={{direction:"column"}}`
`tabletDirection="row"`	`m={{direction:"row"}}`
`mobileDirection="row"`	`s={{direction:"row"}}`

Legacy	New
`tabletColumns={1}`	`m={{columns: 1}}`
`tabletColumns={2}`	`m={{columns: 2}}`
...	...
`tabletColumns={12}`	`m={{columns: 12}}`
`mobileColumns={1}`	`s={{columns: 1}}`
`mobileColumns={2}`	`s={{columns: 2}}`
`mobileColumns={12}`	`s={{columns: 12}}`

Legacy	New
`hide="m"`	`m={{hide: true}}`
`hide="s"`	`s={{hide: true}}`
`show="m"`	`hide m={{hide: false}}`
`show="s"`	`hide s={{hide: false}}`

Legacy	New
`horizontal="space-between"`	`horizontal="between"`
`horizontal="space-around"`	`horizontal="around"`
`horizontal="space-evenly"`	`horizontal="even"`
`vertical="space-between"`	`vertical="between"`
`vertical="space-around"`	`vertical="around"`
`vertical="space-evenly"`	`vertical="even"`

Further updates

We made numerous accessibility improvements: reworked DatePicker, added a custom cursor property to Flex and Grid that supports reactNode, introduced ProgressBar and a lot more! Read the official docs.

Once UI 1.5: Curiosity in code

Launching in the AI-native era: A guide for indie builders