feat: `space`, `columns`, `rows` and box grid item deprecation warnings by pedrobonamin · Pull Request #2182 · sanity-io/ui

pedrobonamin · 2026-03-16T14:26:00Z

Description

Migrated spacing APIs across primitives/components to support gap while keeping space backward compatible, with clear v4 deprecation for space.
Added migration for Grid template props: gridTemplateColumns/gridTemplateRows now preferred over deprecated columns/rows (with precedence to new props).

Prop	Count in monorepo
space	414 results
columns	27 results
rows	1

This will help us have a smaller footprint one we are ready to migrate sanity monorepo to ui v4 or v5, most of the changes in the migration PR are related to this props renames. If we do that before the migration it will help us reduce the noise in the migration PR.
It will also help prepare users for the migration, by doing this change they can start updating the props for when we finally migrate the studio.

What Changed

Spacing migration (`space` -> `gap`, with backward compatibility)

Updated these APIs to accept both props and prefer gap:

Primitives: Inline, Stack, Button, TextInput, Select
Components: TabList (via InlineProps), Menu, MenuItem, MenuGroup, Hotkeys, Breadcrumbs, Tree, TreeItem
Tree context contract: added gap while retaining deprecated space

All affected space props are now documented as deprecated (v4 removal).

Grid migration (`columns`/`rows` -> `gridTemplateColumns`/`gridTemplateRows`)

Added new preferred props:
- gridTemplateColumns
- gridTemplateRows
Kept deprecated aliases:
- columns
- rows
Implemented precedence:
- gridTemplateColumns ?? columns
- gridTemplateRows ?? rows
Updated Grid story defaults/examples and added focused tests.

Deprecates box grid item props column for gridColumn and equivalents.

export interface ResponsiveGridItemProps {
  gridColumn?: GridItemColumn | GridItemColumn[]
  /**
   * @deprecated Use `gridColumn` instead. `column` will be removed in v4.
   */
  column?: GridItemColumn | GridItemColumn[]
  gridColumnStart?: GridItemColumnStart | GridItemColumnStart[]
  /**
   * @deprecated Use `gridColumnStart` instead. `columnStart` will be removed in v4.
   */
  columnStart?: GridItemColumnStart | GridItemColumnStart[]
  gridColumnEnd?: GridItemColumnEnd | GridItemColumnEnd[]
  /**
   * @deprecated Use `gridColumnEnd` instead. `columnEnd` will be removed in v4.
   */
  columnEnd?: GridItemColumnEnd | GridItemColumnEnd[]
  gridRow?: GridItemRow | GridItemRow[]
  /**
   * @deprecated Use `gridRow` instead. `row` will be removed in v4.
   */
  row?: GridItemRow | GridItemRow[]
  gridRowStart?: GridItemRowStart | GridItemRowStart[]
  /**
   * @deprecated Use `gridRowStart` instead. `rowStart` will be removed in v4.
   */
  rowStart?: GridItemRowStart | GridItemRowStart[]
  gridRowEnd?: GridItemRowEnd | GridItemRowEnd[]
  /**
   * @deprecated Use `gridRowEnd` instead. `rowEnd` will be removed in v4.
   */
  rowEnd?: GridItemRowEnd | GridItemRowEnd[]
}

Test strategy

Added/updated focused migration tests to assert:
1. legacy prop still works
2. new prop works
3. new prop takes precedence when both are provided

What to review

Is the deprecation warning ok?

Testing

vercel · 2026-03-16T14:26:16Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
sanity-ui-storybook	Ready	Preview, Comment	Mar 30, 2026 2:21pm
sanity-ui-workshop	Ready	Preview, Comment	Mar 30, 2026 2:21pm

Copilot

Pull request overview

This PR introduces backwards-compatible prop migrations across multiple UI primitives/components by adding new preferred props (gap, gridTemplateColumns, gridTemplateRows) while marking legacy aliases (space, columns, rows) as deprecated for removal in v4, and updates stories/tests to cover the migration behavior.

Changes:

Add gap to multiple primitives/components while keeping deprecated space working, and prefer gap when both are provided.
Add gridTemplateColumns/gridTemplateRows to Grid while keeping deprecated columns/rows, with precedence to the new props.
Update Storybook argTypes and add focused Jest tests asserting legacy support + new-prop precedence.

Reviewed changes

Copilot reviewed 42 out of 42 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
stories/primitives/TextInput.stories.tsx	Exposes `gap` control alongside deprecated `space`.
stories/primitives/Stack.stories.tsx	Adds `gap` control alongside deprecated `space`.
stories/primitives/Select.stories.tsx	Adds `gap` control alongside deprecated `space`.
stories/primitives/Inline.stories.tsx	Adds `gap` control alongside deprecated `space`.
stories/primitives/Grid.stories.tsx	Adds controls for new/deprecated Grid template props.
stories/primitives/Button.stories.tsx	Adds `gap` control and includes it in controls list.
stories/components/Tree.stories.tsx	Adds `gap` control alongside deprecated `space`.
stories/components/TabList.stories.tsx	Adds `gap` control alongside deprecated `space`.
stories/components/MenuItem.stories.tsx	Adds `gap` control alongside deprecated `space`.
stories/components/Menu.stories.tsx	Adds `gap` control alongside deprecated `space`.
stories/components/Hotkeys.stories.tsx	Adds `gap`/`space` controls for spacing migration.
stories/components/Breadcrumbs.stories.tsx	Adds `gap` control alongside deprecated `space`.
src/core/primitives/types.ts	Deprecates `columns`/`rows` and adds `gridTemplateColumns`/`gridTemplateRows` to grid prop types.
src/core/primitives/textInput/textInput.tsx	Adds `gap`, deprecates `space`, and prefers `gap` when provided.
src/core/primitives/textInput/textInput.test.tsx	Tests `space`/`gap` equivalence and `gap` precedence.
src/core/primitives/stack/stack.tsx	Adds `gap`, deprecates `space`, and prefers `gap`.
src/core/primitives/stack/stack.test.tsx	Tests `space`/`gap` equivalence and `gap` precedence.
src/core/primitives/select/select.tsx	Adds `gap`, deprecates `space`, and prefers `gap`.
src/core/primitives/select/select.test.tsx	Tests `space`/`gap` equivalence and `gap` precedence.
src/core/primitives/inline/inline.tsx	Adds `gap`, deprecates `space`, and prefers `gap`.
src/core/primitives/inline/inline.test.tsx	Tests `space`/`gap` equivalence and `gap` precedence.
src/core/primitives/grid/grid.tsx	Adds new Grid template props with precedence over deprecated aliases.
src/core/primitives/grid/grid.test.tsx	Tests old/new Grid template props + precedence behavior.
src/core/primitives/button/button.tsx	Adds `gap`, deprecates `space`, and prefers `gap` for icon/text spacing.
src/core/primitives/button/button.test.tsx	Tests `space`/`gap` behavior and `gap` precedence.
src/core/components/tree/types.ts	Extends Tree context contract to include `gap` while deprecating `space`.
src/core/components/tree/treeItem.tsx	Adds `gap`, deprecates `space`, and prefers `gap` for item spacing.
src/core/components/tree/treeItem.test.tsx	Tests `space`/`gap` behavior and `gap` precedence for TreeItem.
src/core/components/tree/treeGroup.tsx	Switches TreeGroup layout to use context `gap`.
src/core/components/tree/tree.tsx	Adds `gap`, deprecates `space`, and forwards `gap` while keeping context compatibility.
src/core/components/tree/tree.test.tsx	Tests Tree `space`/`gap` behavior and `gap` precedence.
src/core/components/tab/tabList.test.tsx	Tests `gap`/`space` support via Inline styling hook.
src/core/components/menu/menuItem.tsx	Adds `gap`, deprecates `space`, and prefers `gap` for item layout.
src/core/components/menu/menuItem.spacing.test.tsx	Tests MenuItem `space`/`gap` behavior and `gap` precedence.
src/core/components/menu/menuGroup.tsx	Adds `gap`, deprecates `space`, and prefers `gap` for group layout.
src/core/components/menu/menuGroup.spacing.test.tsx	Tests MenuGroup `space`/`gap` behavior and `gap` precedence.
src/core/components/menu/menu.tsx	Adds `gap`, deprecates `space`, and prefers `gap` when rendering Stack.
src/core/components/menu/menu.spacing.test.tsx	Tests Menu `space`/`gap` behavior and `gap` precedence.
src/core/components/hotkeys/hotkeys.tsx	Adds `gap`, deprecates `space`, and prefers `gap` when rendering Inline.
src/core/components/hotkeys/hotkeys.test.tsx	Tests Hotkeys `space`/`gap` behavior and `gap` precedence.
src/core/components/breadcrumbs/breadcrumbs.tsx	Adds `gap`, deprecates `space`, and uses `gap` when rendering stacked overflow list.
src/core/components/breadcrumbs/breadcrumbs.test.tsx	Tests Breadcrumbs `space`/`gap` behavior and `gap` precedence.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

src/core/primitives/inline/inline.tsx

Copilot

Pull request overview

This PR introduces a backwards-compatible spacing migration across primitives/components (space → preferred gap) and updates Grid to prefer gridTemplateColumns/gridTemplateRows over deprecated columns/rows, with Storybook updates and focused migration tests.

Changes:

Add gap props (preferred) while keeping deprecated space across multiple primitives/components, plus corresponding Storybook controls.
Add gridTemplateColumns/gridTemplateRows to Grid (preferred) while retaining deprecated columns/rows with precedence to the new props.
Add focused Jest tests to validate legacy support + new prop precedence.

Reviewed changes

Copilot reviewed 42 out of 42 changed files in this pull request and generated 14 comments.

Show a summary per file

File	Description
stories/primitives/TextInput.stories.tsx	Adds `gap` control alongside existing `space`.
stories/primitives/Stack.stories.tsx	Adds `gap` control alongside existing `space`.
stories/primitives/Select.stories.tsx	Adds `gap` control alongside existing `space`.
stories/primitives/Inline.stories.tsx	Adds `gap` control alongside existing `space`.
stories/primitives/Grid.stories.tsx	Adds controls for deprecated `columns`/`rows` and preferred `gridTemplateColumns`/`gridTemplateRows`.
stories/primitives/Button.stories.tsx	Adds `gap` control and includes `gap` in the WithIcons control include list.
stories/components/Tree.stories.tsx	Adds `gap` control alongside existing `space`.
stories/components/TabList.stories.tsx	Adds `gap` control alongside existing `space`.
stories/components/MenuItem.stories.tsx	Adds `gap` control alongside existing `space`.
stories/components/Menu.stories.tsx	Adds `gap` control alongside existing `space`.
stories/components/Hotkeys.stories.tsx	Adds `gap`/`space` argTypes and imports `getSpaceControls`.
stories/components/Breadcrumbs.stories.tsx	Adds `gap` control alongside existing `space`.
src/core/primitives/types.ts	Deprecates `columns`/`rows` and adds preferred `gridTemplateColumns`/`gridTemplateRows` to `ResponsiveGridProps`.
src/core/primitives/textInput/textInput.tsx	Adds `gap` prop, deprecates `space`, and prefers `gap` when both are provided.
src/core/primitives/textInput/textInput.test.tsx	Adds migration tests for `space`/`gap` behavior and precedence.
src/core/primitives/stack/stack.tsx	Adds `gap` prop, deprecates `space`, and prefers `gap`.
src/core/primitives/stack/stack.test.tsx	Adds migration tests for `space`/`gap` behavior and precedence.
src/core/primitives/select/select.tsx	Adds `gap` prop, deprecates `space`, and prefers `gap`.
src/core/primitives/select/select.test.tsx	Adds migration tests for `space`/`gap` behavior and precedence.
src/core/primitives/inline/inline.tsx	Adds `gap` prop, deprecates `space`, and prefers `gap`.
src/core/primitives/inline/inline.test.tsx	Adds migration tests for `space`/`gap` behavior and precedence.
src/core/primitives/grid/grid.tsx	Adds preferred `gridTemplateColumns`/`gridTemplateRows` with precedence over deprecated `columns`/`rows`.
src/core/primitives/grid/grid.test.tsx	Adds tests validating legacy aliases + new prop precedence.
src/core/primitives/button/button.tsx	Adds `gap` prop, deprecates `space`, and maps to `Flex` gap with precedence to `gap`.
src/core/primitives/button/button.test.tsx	Adds tests for `space` support, `gap` support, and precedence.
src/core/components/tree/types.ts	Extends Tree context contract with `gap` while keeping deprecated `space`.
src/core/components/tree/treeItem.tsx	Adds `gap` prop, deprecates `space`, and prefers `gap` for icon spacing.
src/core/components/tree/treeItem.test.tsx	Adds tests validating `space`/`gap` behavior and precedence for TreeItem spacing.
src/core/components/tree/treeGroup.tsx	Switches TreeGroup spacing usage to `tree.gap`.
src/core/components/tree/tree.tsx	Adds `gap` prop, deprecates `space`, updates context + Stack usage to prefer `gap`.
src/core/components/tree/tree.test.tsx	Adds tests validating Tree `space`/`gap` behavior and precedence.
src/core/components/tab/tabList.test.tsx	Adds tests validating TabList `space`/`gap` behavior and precedence.
src/core/components/menu/menuItem.tsx	Adds `gap` prop, deprecates `space`, and prefers `gap` for internal `Flex` gap.
src/core/components/menu/menuItem.spacing.test.tsx	Adds tests validating MenuItem `space`/`gap` behavior and precedence.
src/core/components/menu/menuGroup.tsx	Adds `gap` prop, deprecates `space`, and prefers `gap` for internal `Flex` gap.
src/core/components/menu/menuGroup.spacing.test.tsx	Adds tests validating MenuGroup `space`/`gap` behavior and precedence.
src/core/components/menu/menu.tsx	Adds `gap` prop, deprecates `space`, and prefers `gap` when rendering internal `Stack`.
src/core/components/menu/menu.spacing.test.tsx	Adds tests validating Menu `space`/`gap` behavior and precedence.
src/core/components/hotkeys/hotkeys.tsx	Adds `gap` prop, deprecates `space`, and prefers `gap` when passing spacing to `Inline`.
src/core/components/hotkeys/hotkeys.test.tsx	Adds tests validating Hotkeys `space`/`gap` behavior and precedence.
src/core/components/breadcrumbs/breadcrumbs.tsx	Adds `gap` prop, deprecates `space`, and prefers `gap` when spacing the overflow menu list.
src/core/components/breadcrumbs/breadcrumbs.test.tsx	Adds tests validating Breadcrumbs `space`/`gap` behavior and precedence.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

src/core/primitives/select/select.test.tsx

src/core/primitives/grid/grid.test.tsx

src/core/components/tree/tree.test.tsx

src/core/components/tab/tabList.test.tsx

src/core/components/menu/menuItem.spacing.test.tsx

src/core/components/tree/treeItem.test.tsx

src/core/components/menu/menuGroup.spacing.test.tsx

src/core/components/hotkeys/hotkeys.test.tsx

src/core/components/breadcrumbs/breadcrumbs.test.tsx

src/core/primitives/stack/stack.test.tsx

pedrobonamin · 2026-03-16T15:38:53Z

@copilot open a new pull request to apply changes based on the comments in this thread

Copilot · 2026-03-16T15:39:02Z

@pedrobonamin I've opened a new pull request, #2183, to work on those changes. Once the pull request is ready, I'll request review from you.

* fix: reset mocks between renders in spacing migration tests Co-authored-by: pedrobonamin <46196328+pedrobonamin@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: pedrobonamin <46196328+pedrobonamin@users.noreply.github.com>

stipsan

Thanks for this! It'll help the migration to v4 for sure 💖

stipsan · 2026-03-27T10:19:30Z

src/core/components/breadcrumbs/breadcrumbs.test.tsx

+import {Box} from '../../primitives'
+import {Breadcrumbs} from './breadcrumbs'
+
+jest.mock('../../primitives', () => {


Oh my goodness, I forgot this repo still uses jest 😧

pedrobonamin added 5 commits March 14, 2026 19:39

feat: deprecate space for gap in Tab, Button, Stack, TextInput

4553f5d

feat: deprecate space for gap for the rest of components

6988a6b

feat: deprecate grid rows and columns for gridTemplate equivalent

aaaa75b

fix: rename space prop to deprecated_space in components body

c0d8d1c

fix: cleanup unncessary changes

9418974

pedrobonamin requested a review from Copilot March 16, 2026 14:26

Copilot started reviewing on behalf of pedrobonamin March 16, 2026 14:26 View session

Copilot AI reviewed Mar 16, 2026

View reviewed changes

src/core/primitives/inline/inline.tsx Outdated Show resolved Hide resolved

fix: lint

dcff031

vercel bot deployed to Preview – sanity-ui-workshop March 16, 2026 14:51 View deployment

vercel bot deployed to Preview – sanity-ui-storybook March 16, 2026 14:51 View deployment

fix: prettier

294af37

vercel bot deployed to Preview – sanity-ui-workshop March 16, 2026 15:18 View deployment

vercel bot deployed to Preview – sanity-ui-storybook March 16, 2026 15:18 View deployment

pedrobonamin requested a review from Copilot March 16, 2026 15:30

Copilot started reviewing on behalf of pedrobonamin March 16, 2026 15:30 View session

Copilot AI reviewed Mar 16, 2026

View reviewed changes

Copilot AI mentioned this pull request Mar 16, 2026

Fix: reset mocks between renders in spacing migration tests #2183

Merged

pedrobonamin changed the title ~~Props deprecation warnings~~ feat: space, columns, rows deprecation warnings Mar 17, 2026

vercel bot deployed to Preview – sanity-ui-workshop March 17, 2026 10:33 View deployment

vercel bot deployed to Preview – sanity-ui-storybook March 17, 2026 10:34 View deployment

pedrobonamin requested review from mariuslundgard and stipsan March 24, 2026 08:44

stipsan previously approved these changes Mar 27, 2026

View reviewed changes

feat: add deprecation warning to box grid item props (#2184)

a4fa187

pedrobonamin dismissed stipsan’s stale review via a4fa187 March 30, 2026 14:20

pedrobonamin changed the title ~~feat: space, columns, rows deprecation warnings~~ feat: space, columns, rows and box grid item deprecation warnings Mar 30, 2026

pedrobonamin requested a review from stipsan March 30, 2026 14:21

vercel bot deployed to Preview – sanity-ui-workshop March 30, 2026 14:21 View deployment

vercel bot deployed to Preview – sanity-ui-storybook March 30, 2026 14:21 View deployment

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: `space`, `columns`, `rows` and box grid item deprecation warnings#2182

feat: `space`, `columns`, `rows` and box grid item deprecation warnings#2182
pedrobonamin wants to merge 9 commits intomainfrom
props-deprecation-warnings

pedrobonamin commented Mar 16, 2026 •

edited

Loading

Uh oh!

vercel bot commented Mar 16, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pedrobonamin commented Mar 16, 2026

Uh oh!

Copilot AI commented Mar 16, 2026

Uh oh!

stipsan left a comment

Uh oh!

stipsan Mar 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

pedrobonamin commented Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

What Changed

Spacing migration (space -> gap, with backward compatibility)

Grid migration (columns/rows -> gridTemplateColumns/gridTemplateRows)

Test strategy

What to review

Testing

Uh oh!

vercel bot commented Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pedrobonamin commented Mar 16, 2026

Uh oh!

Copilot AI commented Mar 16, 2026

Uh oh!

stipsan left a comment

Choose a reason for hiding this comment

Uh oh!

stipsan Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

pedrobonamin commented Mar 16, 2026 •

edited

Loading

Spacing migration (`space` -> `gap`, with backward compatibility)

Grid migration (`columns`/`rows` -> `gridTemplateColumns`/`gridTemplateRows`)

vercel bot commented Mar 16, 2026 •

edited

Loading