Skip to main content

Search (ALPHA)

Alpha feature: invite only

Responsive Widgets are in alpha and available by invitation only on Business and Enterprise plans. Behavior and properties may change. To request access, open a support ticket and name the feature Responsive Widgets (ALPHA).

The Search widget is a search field. It waits until the user stops typing, then runs the onSearch event once with the final text. This avoids running a query on every key press. You can also give it a list of suggestions that shows under the field.

Widget type: WDS_SEARCH_WIDGET

Search widget in a Responsive app
Search widget

How suggestions work​

  • Suggestions show in a list under the field while the field has focus.
  • The list shows only suggestions that contain the typed text. The match ignores case. When the field is empty, all suggestions show.
  • Only text values are shown. Duplicates are removed. The list shows at most 100 suggestions.
  • When the user picks a suggestion, the field text changes to that suggestion and onSuggestionSelect runs right away. Any pending onSearch is canceled.
  • Pressing Escape closes the list.

Content properties​

These properties appear in the Content tab of the property pane.

Data​

Default text string​

Sets the starting search text. Empty by default.

Suggestions array​

An array of text values to show as suggestions. Empty by default.

Examples:

["Alice", "Bob"]
{{Users.data.map((user) => user.name)}}

Label​

Text string​

The label shown above the field. Empty by default, so no label shows.

General​

Placeholder string​

Text shown inside the field when it is empty. Default: Search.

Debounce (ms) number​

How long the field waits after the last key press before onSearch runs, in milliseconds. Must be from 0 to 2000. Default: 250.

If a bound value is not a number, the widget uses 250. Values outside the range are set to the nearest limit.

Visible boolean​

Controls whether the widget shows in the app. On by default.

Disabled boolean​

Stops users from typing in the field. Off by default.

Animate loading boolean​

Shows a loading animation while the widget loads. On by default.

Style properties​

These properties appear in the Style tab of the property pane.

General​

Size string​

Sets the size of the search field. Options:

  • Small
  • Medium (default)
  • Large

Custom styling​

These settings are in the Custom styling section, at the end of the Style tab. An empty setting uses the theme value. For theme colors, dark mode, and the rules for custom CSS, see Custom styling.

Accent color string​

Builds the hover, pressed, focus, and text colors of this widget from one color, in light and dark mode. Lists and menus that the widget opens use them too. Empty means the accent of the nearest container that sets one, or the theme accent.

Background string​

Sets the background of the input field box. Takes a theme color or a custom color.

Text color string​

Sets the text color of the input field box. Takes a theme color or a custom color. When it is empty and Background is set, the widget picks a readable text color.

Border color string​

Sets the border color of the input field box. Takes a theme color or a custom color. A color with no Border width draws a thin border.

Border width string​

Sets the border width of the input field box. Options: From theme (default), None, Thin, Medium, Thick. You cannot bind this property.

Corners string​

Sets the corner radius of the input field box. Options: From theme (default), Sharp, Rounded, Pill. You cannot bind this property.

Custom CSS string​

Adds plain CSS to this widget. Rules apply only inside the widget, and & is the box around the widget, its label included, not the part inside it. To style an inner part, use its element selector, for example button or input. You cannot bind this property.

Reference properties​

Reference properties let you read the widget's state in bindings and code, for example {{Search1.isVisible}}. You cannot set them directly.

text string​

The current search text. It updates when onSearch runs or when the user picks a suggestion. Use it as the search term in a query.

Example:

{{Search1.text}}

isVisible boolean​

Shows whether the widget is visible.

Example:

{{Search1.isVisible}}

Methods​

Methods let you change the widget's properties from code, for example in a JS Object.

setVisibility (param: boolean): Promise​

Shows or hides the widget.

Example:

Search1.setVisibility(true)

setDisabled (param: boolean): Promise​

Turns Disabled on or off.

Example:

Search1.setDisabled(false)

setValue (param: string): Promise​

Sets the search text.

Example:

Search1.setValue("invoice")

Events​

onSearch​

Runs when the user stops typing for the Debounce (ms) time. It runs once per pause, with the final text in Search1.text.

onSuggestionSelect​

Runs when the user picks a suggestion from the list.