# Migrating to @godxjp/ui v33

Off-cycle approved: Pham Thai Duong 2026-10-15 — FilterBar overflow="scroll" taught consumers to build sideways-scrolling filter bars; removing it cannot wait for the next scheduled major.

v33 removes one thing: the horizontally scrolling filter bar. `FilterBar` (and its alias
`Toolbar`) no longer accepts an `overflow` prop. A filter bar now always wraps. All six packages
(`@godxjp/ui`, `@godxjp/ui-mcp`, `@godxjp/markdown`, `@godxjp/editor`, `@godxjp/block-editor` and
`@godxjp/chat`) move to 33.0.0 together.

## Why

The library recommended `overflow="scroll"` for list pages with many filters and long Japanese,
English or Vietnamese labels. A consumer list page followed that advice, and the result was
measured at 1240px in Vietnamese: the filter strip was 1945px wide inside a 921px frame, the first
filter label was clipped at the inline-start edge, and the user had to scroll sideways to reach
filters they could not see. Leading products do not do this. GitHub, Linear, Gmail, Jira and
Shopify Polaris IndexFilters never scroll a filter bar sideways; they let it wrap, or they collapse
the rarely used filters behind a single "More filters" or "Add filter" control.

## Breaking changes

### FilterBar / Toolbar `overflow` is removed

- The `overflow` prop is gone from `FilterBar` and `Toolbar`, and the `FilterBarOverflowProp` type
  is no longer exported. Passing `overflow` is now a TypeScript error.
- The strip no longer carries a `data-overflow` attribute, and the
  `.ui-toolbar[data-overflow="scroll"]` rules are removed from the stylesheet.
- The bar always wraps: below 640px the filters stack in one column, from 640px up they flow onto
  as many rows as they need. This is the behaviour the old default `overflow="wrap"` already had,
  so a bar that never passed `overflow`, or passed `overflow="wrap"`, renders exactly as before.

### Token `--filter-bar-scroll-padding-y` is removed

It only reserved the scrollbar gutter under the removed scroll strip. A theme that sets it can
delete the line; nothing reads it any more.

`Tabs overflow`, `Topbar overflow` and the chat attachments `overflow` are different components
and are unchanged.

## How to upgrade

1. Upgrade all six packages to 33.0.x together.
2. Run `npx godxjp-ui audit <src>`. The new
   `filter-bar-no-overflow` rule reports every `<FilterBar>` or `<Toolbar>` that still passes
   `overflow`. The TypeScript build reports the same places.
3. Delete the `overflow` prop at each place it reports. If a page used `overflow="scroll"` because
   it has many filters, check how tall the wrapped bar is. When it takes more than two rows, keep
   the few filters people use most in the bar and move the rest behind one "More filters" Button
   that opens a Sheet holding them as `FilterBarGroup`s. The library has no dedicated component for
   this; it is a composition of Button, Sheet and FilterBarGroup, and the applied filters can still
   show as `chips` on the bar.
4. Remove any page CSS that targeted `[data-overflow]` on the filter strip, and any theme line that
   set `--filter-bar-scroll-padding-y`.
5. Run `npx godxjp-ui sync-rules` and restart your coding agent so it stops recommending the
   removed prop.

## Support

v32 receives no further releases. A security fix for v32 is an owner exception, decided case by
case.