DataGridPicker

Patterns

Dense Choice Matrix

When to use: Present many short options in a grid where the picker shape is part of the product experience.

Composition notes: Use DataGridPickerItem for every selectable cell and let the picker layer own active and selected styling.

Trade-offs: The layout is space-efficient, but each item needs strong visual clarity because labels are short.

import {
  DataGridPicker,
  DataGridPickerItem,
  DataGridPickerRow,
  DataGridPickerRowGroup,
} from '@vega-ui/react';

const months = [
  ['Jan', 'Feb', 'Mar', 'Apr'],
  ['May', 'Jun', 'Jul', 'Aug'],
  ['Sep', 'Oct', 'Nov', 'Dec'],
];

Paged Picker

When to use: The choice set is large enough that it should be paged horizontally.

Composition notes: Wrap the grid in DataGridPickerScroller and render one page component inside DataGridPickerScrollerContent. The page reads its index from useIndexedSnapScrollerContext, derives its data and row numbers from it, and passes it as scope of its row group.

Trade-offs: You gain density and swipe-like paging, but focus and active-state restoration become more important.

import { useRef, useState } from 'react';
import { ChevronLeft, ChevronRight } from '@vega-ui/icons';
import {
  DataGridPicker,
  DataGridPickerItem,
  DataGridPickerRow,
  DataGridPickerRowGroup,
  DataGridPickerScroller,
  DataGridPickerScrollerContent,
  Icon,
  IconButton,
  Text,

Comparison

Quick Decision Rule

Choose DataGridPicker when the UI needs a grid-shaped picker with VegaUI visual semantics. Choose DataGridSelectable when selection behavior matters but the visual layer should be fully custom.

DataGridPicker vs DataGridSelectable

Use DataGridPicker when the component should look and behave like a picker.

Use DataGridSelectable when only the behavior layer should be reused.

DataGridPicker vs MonthPicker

Use DataGridPicker when the chosen values are generic and not specifically months.

Use MonthPicker when month-domain helpers and semantics are needed.

DataGridPicker vs DayPicker

Use DataGridPicker when the grid is generic.

Use DayPicker when date math, visible month context, and day semantics matter.

Choose This Component When

• the UI needs a dense, selectable grid
• size and variant should follow VegaUI picker semantics
• the domain is custom but still picker-shaped

Do Not Choose This Component When

• a plain data table is needed
• the visual layer should be completely custom
• a richer domain-specific picker already exists

Troubleshooting

The Picker Scrolls But Focus Restores To The Wrong Page

Symptom

After paging, focus jumps to an unexpected item or the first item on the wrong page.

Likely Cause

Paged row groups do not provide stable scope, so the grid cannot distinguish one page from another.

How To Verify

• inspect the row-group props in the paged composition
• compare behavior with and without explicit scope values

Fix

Provide stable scope for each DataGridPickerRowGroup in scroller-based layouts.

Selected And Active States Are Hard To Distinguish

Symptom

Users can focus or select items, but the visual states look too similar.

Likely Cause

Custom item rendering hides the picker item semantics.

How To Verify

• inspect the final picker item DOM and classes
• compare the custom render with the default item treatment

Fix

Preserve the picker item layer and ensure active, selected, and disabled states remain visibly distinct.

The Picker Feels Like A Table Instead Of A Picker

Symptom

The UI works technically, but it reads as a generic data grid rather than a selection control.

Likely Cause

The composition uses table-like content and custom cell styling that ignores the picker semantics.

How To Verify

• compare the product rendering with the shipped picker stories
• inspect whether DataGridPickerItem still owns the selection surface

Fix

Lean on the picker item layer or move back to DataGridSelectable if a fully custom visual system is the real goal.