Once UI 1.4 migration guide: The breakpoint object

Lorant

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

<LayoutProvider>
  {children}
</LayoutProvider>

Add it to your layout.tsx or Providers.tsx.

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:

<Row fillWidth tabletDirection="column">
  {children}
</Row>

New syntax:

<Row fillWidth m={{direction: "column"}}>
  {children}
</Row>

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:

<Column show="m">
  {children}
</Column>

New syntax:

<Column hide m={{hide: false}}>
  {children}
</Column>

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

<Grid columns={8} tabletColumns={4} mobileColumns={2}>
  {children}
</Column>

New syntax:

<Grid columns={8} m={{columns: 4}} s={{columns: 2}}>
  {children}
</Column>

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.

<Column position="sticky" m={{position: "absolute"}}>
  {children}
</Column>

Also notice how top is not set in the above example, since it will default to 0 if not specified when using sticky position.

<Column position="sticky" m={{position: "absolute", style: {top: "24"}}}>
  {children}
</Column>

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"