Widget Selection Modal

The Widget Selection Modal provides a dialog interface for selecting and inserting widgets into the current layout. It is typically triggered from within the widget editor when adding a new widget to a container or layout slot.

Overview

The modal displays all available widgets organized by category, allowing users to browse and select a widget to insert. Each widget entry shows its title and an optional description to help identify the right widget for the task.

The modal includes a search input at the top of the widget list. Typing in the search field filters the displayed widgets in real time, matching against both widget titles and descriptions.

  • Filtering: Results are narrowed as the user types. Only widgets whose title or description contains the search query (case-insensitive) are shown.
  • Empty state: If the search query yields no matching widgets, a "no results" message is displayed in place of the widget grid.
  • Reset on close: The search field is automatically cleared whenever the modal is closed, ensuring a clean state the next time it is opened.

The search input can be located in the DOM via the test ID widget-selection-search.

Widget Categories

Widgets are grouped into categories. A category section is only rendered when it contains at least one widget that matches the current search query. When no search query is active, all categories with at least one catalog-visible widget are shown.

Selecting a Widget

Clicking a widget card confirms the selection. The chosen widget is passed to the parent via the onSelectWidget callback, and the modal closes automatically.

Closing the Modal

The modal can be dismissed using the close button in the header or by confirming a widget selection. In both cases the search query is reset to an empty string before the onClose callback is invoked.

Props

Prop Type Description
onSelectWidget (widgetName: string) => void Called with the selected widget's name when a widget card is clicked.
onClose () => void Called when the modal is dismissed without a selection, or after a widget is selected.
  • Widget Catalog — The sidebar catalog panel, which shares the same filtering logic via getFilteredWidgetsByCategory.
  • Widget System — Overview of widget architecture, registration, and the registry service.
Markdown | llm.txt