SearchField

Search input field with clear button and search icon

Usage

1import { SearchField } from '@lenso/ui';

1"use client";2
3// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.4import { Label, SearchField } from "@lenso/ui";5import * as stylex from "@stylexjs/stylex";6const styles = stylex.create({ input: { width: 280 } });7
8export function Basic() {9  return (10    <SearchField name="search">11      <Label>Search</Label>12      <SearchField.Group>13        <SearchField.SearchIcon />14        <SearchField.Input xstyle={styles.input} placeholder="Search..." />15        <SearchField.ClearButton />16      </SearchField.Group>17    </SearchField>18  );19}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Anatomy

1import {SearchField, Label, Description, FieldError} from '@lenso/ui';2
3export default () => (4  <SearchField>5    <Label />6    <SearchField.Group>7      <SearchField.SearchIcon />8      <SearchField.Input />9      <SearchField.ClearButton />10    </SearchField.Group>11    <Description />12    <FieldError />13  </SearchField>14)

SearchField allows users to enter and clear a search query. It includes a search icon and an optional clear button for easy reset.

Examples

Variants

The SearchField component supports two visual variants:

primary (default) - Standard styling with shadow, suitable for most use cases
secondary - Lower emphasis variant without shadow, suitable for use in Surface components

1"use client";2// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.3import { Label, SearchField } from "@lenso/ui";4import * as stylex from "@stylexjs/stylex";5const styles = stylex.create({6  root: { display: "flex", flexDirection: "column", gap: 16 },7  input: { width: 280 },8});9export function Variants() {10  return (11    <div {...stylex.props(styles.root)}>12      <SearchField name="primary-search" variant="primary">13        <Label>Primary variant</Label>14        <SearchField.Group>15          <SearchField.SearchIcon />16          <SearchField.Input xstyle={styles.input} placeholder="Search..." />17          <SearchField.ClearButton />18        </SearchField.Group>19      </SearchField>20      <SearchField name="secondary-search" variant="secondary">21        <Label>Secondary variant</Label>22        <SearchField.Group>23          <SearchField.SearchIcon />24          <SearchField.Input xstyle={styles.input} placeholder="Search..." />25          <SearchField.ClearButton />26        </SearchField.Group>27      </SearchField>28    </div>29  );30}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

In Surface

When used inside a Surface component, use variant="secondary" to apply the lower emphasis variant suitable for surface backgrounds.

1"use client";2// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.3import { Description, Label, SearchField, Surface } from "@lenso/ui";4import * as stylex from "@stylexjs/stylex";5const styles = stylex.create({6  root: {7    display: "flex",8    width: "100%",9    maxWidth: 384,10    flexDirection: "column",11    gap: 16,12    borderRadius: 24,13    padding: 24,14  },15  input: { width: "100%" },16});17export function OnSurface() {18  return (19    <Surface xstyle={styles.root}>20      <SearchField name="search" variant="secondary">21        <Label>Search</Label>22        <SearchField.Group>23          <SearchField.SearchIcon />24          <SearchField.Input xstyle={styles.input} placeholder="Search..." />25          <SearchField.ClearButton />26        </SearchField.Group>27        <Description>Enter keywords to search</Description>28      </SearchField>29      <SearchField name="search-2" variant="secondary">30        <Label>Advanced search</Label>31        <SearchField.Group>32          <SearchField.SearchIcon />33          <SearchField.Input xstyle={styles.input} placeholder="Advanced search..." />34          <SearchField.ClearButton />35        </SearchField.Group>36        <Description>Use filters to refine your search</Description>37      </SearchField>38    </Surface>39  );40}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

With Description

1"use client";2// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.3import { Description, Label, SearchField } from "@lenso/ui";4import * as stylex from "@stylexjs/stylex";5const styles = stylex.create({6  root: { display: "flex", flexDirection: "column", gap: 16 },7  input: { width: 280 },8});9export function WithDescription() {10  return (11    <div {...stylex.props(styles.root)}>12      <SearchField name="search">13        <Label>Search products</Label>14        <SearchField.Group>15          <SearchField.SearchIcon />16          <SearchField.Input xstyle={styles.input} placeholder="Search products..." />17          <SearchField.ClearButton />18        </SearchField.Group>19        <Description>Enter keywords to search for products</Description>20      </SearchField>21      <SearchField name="search-users">22        <Label>Search users</Label>23        <SearchField.Group>24          <SearchField.SearchIcon />25          <SearchField.Input xstyle={styles.input} placeholder="Search users..." />26          <SearchField.ClearButton />27        </SearchField.Group>28        <Description>Search by name, email, or username</Description>29      </SearchField>30    </div>31  );32}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Required Field

1"use client";2// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.3import { Description, Label, SearchField } from "@lenso/ui";4import * as stylex from "@stylexjs/stylex";5const styles = stylex.create({6  root: { display: "flex", flexDirection: "column", gap: 16 },7  input: { width: 280 },8});9export function Required() {10  return (11    <div {...stylex.props(styles.root)}>12      <SearchField name="search">13        <Label>Search</Label>14        <SearchField.Group>15          <SearchField.SearchIcon />16          <SearchField.Input required xstyle={styles.input} placeholder="Search..." />17          <SearchField.ClearButton />18        </SearchField.Group>19      </SearchField>20      <SearchField name="search-query">21        <Label>Search query</Label>22        <SearchField.Group>23          <SearchField.SearchIcon />24          <SearchField.Input required xstyle={styles.input} placeholder="Enter search query..." />25          <SearchField.ClearButton />26        </SearchField.Group>27        <Description>Minimum 3 characters required</Description>28      </SearchField>29    </div>30  );31}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Disabled State

1"use client";2// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.3import { Description, Label, SearchField } from "@lenso/ui";4import * as stylex from "@stylexjs/stylex";5const styles = stylex.create({6  root: { display: "flex", flexDirection: "column", gap: 16 },7  input: { width: 280 },8});9export function Disabled() {10  return (11    <div {...stylex.props(styles.root)}>12      <SearchField disabled name="search">13        <Label>Search</Label>14        <SearchField.Group>15          <SearchField.SearchIcon />16          <SearchField.Input17            xstyle={styles.input}18            value="Disabled search"19            placeholder="Search..."20          />21          <SearchField.ClearButton />22        </SearchField.Group>23        <Description>This search field is disabled</Description>24      </SearchField>25      <SearchField disabled name="search-empty">26        <Label>Search</Label>27        <SearchField.Group>28          <SearchField.SearchIcon />29          <SearchField.Input xstyle={styles.input} placeholder="Search..." />30          <SearchField.ClearButton />31        </SearchField.Group>32        <Description>This search field is disabled</Description>33      </SearchField>34    </div>35  );36}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Full Width

1"use client";2// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.3import { Label, SearchField } from "@lenso/ui";4import * as stylex from "@stylexjs/stylex";5const styles = stylex.create({ root: { width: 400 } });6export function FullWidth() {7  return (8    <div {...stylex.props(styles.root)}>9      <SearchField fullWidth name="search">10        <Label>Search</Label>11        <SearchField.Group>12          <SearchField.SearchIcon />13          <SearchField.Input placeholder="Search..." />14          <SearchField.ClearButton />15        </SearchField.Group>16      </SearchField>17    </div>18  );19}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Validation

Use isInvalid together with FieldError to surface validation messages.

1"use client";2// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.3import { FieldError, Label, SearchField } from "@lenso/ui";4import * as stylex from "@stylexjs/stylex";5const styles = stylex.create({6  root: { display: "flex", flexDirection: "column", gap: 16 },7  input: { width: 280 },8});9export function Validation() {10  return (11    <div {...stylex.props(styles.root)}>12      <SearchField invalid name="search">13        <Label>Search</Label>14        <SearchField.Group>15          <SearchField.SearchIcon />16          <SearchField.Input required value="ab" xstyle={styles.input} placeholder="Search..." />17          <SearchField.ClearButton />18        </SearchField.Group>19        <FieldError match>Search query must be at least 3 characters</FieldError>20      </SearchField>21      <SearchField invalid name="search-invalid">22        <Label>Search</Label>23        <SearchField.Group>24          <SearchField.SearchIcon />25          <SearchField.Input xstyle={styles.input} placeholder="Search..." value="invalid@query" />26          <SearchField.ClearButton />27        </SearchField.Group>28        <FieldError match>Invalid characters in search query</FieldError>29      </SearchField>30    </div>31  );32}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Controlled

Control the value to synchronize with other components or perform custom formatting.

1"use client";2// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.3import { Button, Description, Label, SearchField } from "@lenso/ui";4import * as React from "react";5import * as stylex from "@stylexjs/stylex";6const styles = stylex.create({7  root: { display: "flex", flexDirection: "column", gap: 16 },8  actions: { display: "flex", gap: 8 },9  input: { width: 280 },10});11export function Controlled() {12  const [value, setValue] = React.useState("");13  return (14    <div {...stylex.props(styles.root)}>15      <SearchField name="search">16        <Label>Search</Label>17        <SearchField.Group>18          <SearchField.SearchIcon />19          <SearchField.Input20            xstyle={styles.input}21            placeholder="Search..."22            value={value}23            onValueChange={setValue}24          />25          <SearchField.ClearButton />26        </SearchField.Group>27        <Description>Current value: {value || "(empty)"}</Description>28      </SearchField>29      <div {...stylex.props(styles.actions)}>30        <Button variant="tertiary" onClick={() => setValue("")}>31          Clear32        </Button>33        <Button variant="tertiary" onClick={() => setValue("example query")}>34          Set example35        </Button>36      </div>37    </div>38  );39}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Form Example

Complete form integration with validation and submission handling.

1"use client";2// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.3import { Button, Description, FieldError, Form, Label, SearchField, Spinner } from "@lenso/ui";4import * as React from "react";5import * as stylex from "@stylexjs/stylex";6const styles = stylex.create({7  root: { display: "flex", width: 280, flexDirection: "column", gap: 16 },8  full: { width: "100%" },9});10export function FormExample() {11  const [value, setValue] = React.useState("");12  const [isSubmitting, setIsSubmitting] = React.useState(false);13  const timer = React.useRef<ReturnType<typeof setTimeout> | null>(null);14  React.useEffect(15    () => () => {16      if (timer.current) clearTimeout(timer.current);17    },18    [],19  );20  const MIN_LENGTH = 3;21  const isInvalid = value.length > 0 && value.length < MIN_LENGTH;22  const handleSubmit = (event: React.FormEvent) => {23    event.preventDefault();24    if (value.length < MIN_LENGTH || isSubmitting) return;25    setIsSubmitting(true);26    timer.current = setTimeout(() => {27      console.log("Search submitted:", { query: value });28      setValue("");29      setIsSubmitting(false);30    }, 1500);31  };32  return (33    <Form xstyle={styles.root} onSubmit={handleSubmit}>34      <SearchField invalid={isInvalid} name="search">35        <Label>Search products</Label>36        <SearchField.Group>37          <SearchField.SearchIcon />38          <SearchField.Input39            required40            xstyle={styles.full}41            placeholder="Search products..."42            value={value}43            onValueChange={setValue}44          />45          <SearchField.ClearButton />46        </SearchField.Group>47        {isInvalid ? (48          <FieldError match>Search query must be at least {MIN_LENGTH} characters</FieldError>49        ) : (50          <Description style={{ display: "block" }}>51            Enter at least {MIN_LENGTH} characters to search52          </Description>53        )}54      </SearchField>55      <Button56        xstyle={styles.full}57        disabled={value.length < MIN_LENGTH}58        isLoading={isSubmitting}59        type="submit"60        variant="primary"61      >62        {isSubmitting ? (63          <>64            <Spinner color="current" size="sm" />65            Searching...66          </>67        ) : (68          "Search"69        )}70      </Button>71    </Form>72  );73}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

With Validation

Implement custom validation logic with controlled values.

1"use client";2// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.3import { Description, FieldError, Label, SearchField } from "@lenso/ui";4import * as React from "react";5import * as stylex from "@stylexjs/stylex";6const styles = stylex.create({7  root: { display: "flex", flexDirection: "column", gap: 16 },8  input: { width: 280 },9});10export function WithValidation() {11  const [value, setValue] = React.useState("");12  const isInvalid = value.length > 0 && value.length < 3;13  return (14    <div {...stylex.props(styles.root)}>15      <SearchField invalid={isInvalid} name="search">16        <Label>Search</Label>17        <SearchField.Group>18          <SearchField.SearchIcon />19          <SearchField.Input20            required21            xstyle={styles.input}22            placeholder="Search..."23            value={value}24            onValueChange={setValue}25          />26          <SearchField.ClearButton />27        </SearchField.Group>28        {isInvalid ? (29          <FieldError match>Search query must be at least 3 characters</FieldError>30        ) : (31          <Description style={{ display: "block" }}>32            Enter at least 3 characters to search33          </Description>34        )}35      </SearchField>36    </div>37  );38}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Custom Icons

Customize the search icon and clear button icons.

1"use client";2// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.3import { Description, Label, SearchField } from "@lenso/ui";4import * as stylex from "@stylexjs/stylex";5const styles = stylex.create({6  root: { display: "flex", flexDirection: "column", gap: 16 },7  input: { width: 280 },8});9export function CustomIcons() {10  return (11    <div {...stylex.props(styles.root)}>12      <SearchField name="search-custom">13        <Label>Search (Custom Icons)</Label>14        <SearchField.Group>15          <SearchField.SearchIcon16            height="16"17            viewBox="0 0 16 16"18            width="16"19            xmlns="http://www.w3.org/2000/svg"20            fill="none"21            stroke="none"22          >23            <path24              clipRule="evenodd"25              d="M12.5 4c0 .174-.071.513-.885.888S9.538 5.5 8 5.5s-2.799-.237-3.615-.612C3.57 4.513 3.5 4.174 3.5 4s.071-.513.885-.888S6.462 2.5 8 2.5s2.799.237 3.615.612c.814.375.885.714.885.888m-1.448 2.66C10.158 6.888 9.115 7 8 7s-2.158-.113-3.052-.34l1.98 2.905c.21.308.322.672.322 1.044v3.37q.088.02.25.021c.422 0 .749-.14.95-.316c.185-.162.3-.38.3-.684v-2.39c0-.373.112-.737.322-1.045zM8 1c3.314 0 6 1 6 3a3.24 3.24 0 0 1-.563 1.826l-3.125 4.584a.35.35 0 0 0-.062.2V13c0 1.5-1.25 2.5-2.75 2.5s-1.75-1-1.75-1v-3.89a.35.35 0 0 0-.061-.2L2.563 5.826A3.24 3.24 0 0 1 2 4c0-2 2.686-3 6-3m-.88 12.936q-.015-.008-.013-.01z"26              fill="currentColor"27              fillRule="evenodd"28            />29          </SearchField.SearchIcon>30          <SearchField.Input xstyle={styles.input} placeholder="Search..." />31          <SearchField.ClearButton>32            <svg33              aria-hidden="true"34              height="16"35              viewBox="0 0 16 16"36              width="16"37              xmlns="http://www.w3.org/2000/svg"38            >39              <path40                clipRule="evenodd"41                d="M8 15A7 7 0 1 0 8 1a7 7 0 0 0 0 14M6.53 5.47a.75.75 0 0 0-1.06 1.06L6.94 8L5.47 9.47a.75.75 0 1 0 1.06 1.06L8 9.06l1.47 1.47a.75.75 0 1 0 1.06-1.06L9.06 8l1.47-1.47a.75.75 0 1 0-1.06-1.06L8 6.94z"42                fill="currentColor"43                fillRule="evenodd"44              />45            </svg>46          </SearchField.ClearButton>47        </SearchField.Group>48        <Description>Custom icon children</Description>49      </SearchField>50    </div>51  );52}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

With Keyboard Shortcut

Add keyboard shortcuts to quickly focus the search field.

1"use client";2// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.3import { Description, Kbd, Label, SearchField } from "@lenso/ui";4import * as React from "react";5import * as stylex from "@stylexjs/stylex";6const styles = stylex.create({7  root: { display: "flex", flexDirection: "column", gap: 16 },8  input: { width: 280 },9  hint: {10    display: "flex",11    alignItems: "center",12    gap: 8,13    fontSize: 14,14    color: "var(--default-500)",15  },16});17export function WithKeyboardShortcut() {18  const inputRef = React.useRef<HTMLInputElement>(null);19  const [value, setValue] = React.useState("");20  React.useEffect(() => {21    const handleKeyDown = (event: KeyboardEvent) => {22      if (23        event.shiftKey &&24        event.key === "S" &&25        !event.metaKey &&26        !event.ctrlKey &&27        !event.altKey28      ) {29        event.preventDefault();30        inputRef.current?.focus();31      }32      if (event.key === "Escape" && document.activeElement === inputRef.current)33        inputRef.current?.blur();34    };35    window.addEventListener("keydown", handleKeyDown);36    return () => window.removeEventListener("keydown", handleKeyDown);37  }, []);38  return (39    <div {...stylex.props(styles.root)}>40      <div>41        <SearchField name="search">42          <Label>Search</Label>43          <SearchField.Group>44            <SearchField.SearchIcon />45            <SearchField.Input46              ref={inputRef}47              xstyle={styles.input}48              placeholder="Search..."49              value={value}50              onValueChange={setValue}51            />52            <SearchField.ClearButton />53          </SearchField.Group>54          <Description>Use keyboard shortcut to quickly focus this field</Description>55        </SearchField>56      </div>57      <div {...stylex.props(styles.hint)}>58        <span>Press</span>59        <Kbd>60          <Kbd.Abbr keyValue="shift" />61          <Kbd.Content>S</Kbd.Content>62        </Kbd>63        <span>to focus the search field</span>64      </div>65    </div>66  );67}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Render Function

1"use client";2// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.3import { Label, SearchField } from "@lenso/ui";4import * as stylex from "@stylexjs/stylex";5const styles = stylex.create({ input: { width: 280 } });6export function RenderFunction() {7  return (8    <SearchField name="search" render={(props) => <div {...props} data-custom="foo" />}>9      <Label>Search</Label>10      <SearchField.Group>11        <SearchField.SearchIcon />12        <SearchField.Input xstyle={styles.input} placeholder="Search..." />13        <SearchField.ClearButton />14      </SearchField.Group>15    </SearchField>16  );17}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Customization

Tailwind CSS

1"use client";2// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.3import { Label, SearchField } from "@lenso/ui";4import * as stylex from "@stylexjs/stylex";5const styles = stylex.create({6  root: { width: "100%", maxWidth: 256 },7  label: { fontWeight: 500, color: "var(--foreground)" },8  group: { borderRadius: 12, backgroundColor: "var(--default)" },9  muted: { color: "var(--muted)" },10  input: { "::placeholder": { color: "var(--muted)" } },11});12export function CustomStyles() {13  return (14    <SearchField xstyle={styles.root} name="docs" variant="secondary">15      <Label xstyle={styles.label}>Search docs</Label>16      <SearchField.Group xstyle={styles.group}>17        <SearchField.SearchIcon xstyle={styles.muted} />18        <SearchField.Input xstyle={styles.input} placeholder="Components, guides..." />19        <SearchField.ClearButton xstyle={styles.muted} />20      </SearchField.Group>21    </SearchField>22  );23}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Global CSS

SearchField uses CSS classes that can be customized. Override the component classes to match your design system.

1@layer components {2  .search-field {3    @apply flex flex-col gap-1;4  }5
6  /* When invalid, the description is hidden automatically */7  .search-field[data-invalid],8  .search-field[aria-invalid] {9    [data-slot="description"] {10      @apply hidden;11    }12  }13
14  .search-field__group {15    @apply bg-field text-field-foreground shadow-field rounded-field inline-flex h-9 items-center overflow-hidden border;16  }17
18  .search-field__input {19    @apply flex-1 rounded-none border-0 bg-transparent px-3 py-2 shadow-none outline-none;20  }21
22  .search-field__search-icon {23    @apply text-field-placeholder pointer-events-none shrink-0 ml-3 mr-0 size-4;24  }25
26  .search-field__clear-button {27    @apply mr-1 shrink-0;28  }29}

Styling Reference

HeroUI follows the BEM methodology to ensure component variants and states are reusable and easy to customize.

CSS Classes

Base Classes [!toc]

.search-field – Root container with minimal styling (flex flex-col gap-1)
.search-field__group – Container for search icon, input, and clear button with border and background styling
.search-field__input – The search input field
.search-field__search-icon – The search icon displayed on the left
.search-field__clear-button – Button to clear the search field

Variant Classes [!toc]

.search-field--primary – Primary variant with shadow (default)
.search-field--secondary – Secondary variant without shadow, suitable for use in surfaces

Note: Child components (Label, Description, FieldError) have their own CSS classes and styling. See their respective documentation for customization options.

Interactive States

SearchField automatically manages these data attributes based on its state:

Invalid: [data-invalid="true"] or [aria-invalid="true"] - Automatically hides the description slot when invalid
Disabled: [data-disabled="true"] - Applied when isDisabled is true
Focus Within: [data-focus-within="true"] - Applied when the input is focused
Focus Visible: [data-focus-visible="true"] - Applied when focus is visible (keyboard navigation)
Hovered: [data-hovered="true"] - Applied when hovering over the group
Empty: [data-empty="true"] - Applied when the field is empty (hides clear button)

Additional attributes are available through render props (see SearchFieldRenderProps below).

API Reference

SearchField

SearchField inherits all props from React Aria's SearchField component.

Base Props

Prop	Type	Default	Description
`children`	`React.ReactNode \| (values: SearchFieldRenderProps) => React.ReactNode`	-	Child components (Label, Group, Input, etc.) or render function.
`className`	`string \| (values: SearchFieldRenderProps) => string`	-	CSS classes for styling, supports render props.
`style`	`React.CSSProperties \| (values: SearchFieldRenderProps) => React.CSSProperties`	-	Inline styles, supports render props.
`fullWidth`	`boolean`	`false`	Whether the search field should take full width of its container
`id`	`string`	-	The element's unique identifier.
`variant`	`"primary" \| "secondary"`	`"primary"`	Visual variant of the component. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces.
`render`	`DOMRenderFunction<keyof React.JSX.IntrinsicElements, SearchFieldRenderProps>`	-	Overrides the default DOM element with a custom render function.

Value Props

Prop	Type	Default	Description
`value`	`string`	-	Current value (controlled).
`defaultValue`	`string`	-	Default value (uncontrolled).
`onChange`	`(value: string) => void`	-	Handler called when the value changes.

Validation Props

Prop	Type	Default	Description
`isRequired`	`boolean`	`false`	Whether user input is required before form submission.
`isInvalid`	`boolean`	-	Whether the value is invalid.
`validate`	`(value: string) => ValidationError \| true \| null \| undefined`	-	Custom validation function.
`validationBehavior`	`'native' \| 'aria'`	`'native'`	Whether to use native HTML form validation or ARIA attributes.
`validationErrors`	`string[]`	-	Server-side validation errors.

State Props

Prop	Type	Default	Description
`isDisabled`	`boolean`	-	Whether the input is disabled.
`isReadOnly`	`boolean`	-	Whether the input can be selected but not changed.

Form Props

Prop	Type	Default	Description
`name`	`string`	-	Name of the input element, for HTML form submission.
`autoFocus`	`boolean`	-	Whether the element should receive focus on render.

Event Props

Prop	Type	Default	Description
`onSubmit`	`(value: string) => void`	-	Handler called when the user submits the search (Enter key).
`onClear`	`() => void`	-	Handler called when the clear button is pressed.

Accessibility Props

Prop	Type	Default	Description
`aria-label`	`string`	-	Accessibility label when no visible label is present.
`aria-labelledby`	`string`	-	ID of elements that label this field.
`aria-describedby`	`string`	-	ID of elements that describe this field.
`aria-details`	`string`	-	ID of elements with additional details.

Composition Components

SearchField works with these separate components that should be imported and used directly:

SearchField.Group - Container for search icon, input, and clear button
SearchField.Input - The search input field
SearchField.SearchIcon - The search icon displayed on the left
SearchField.ClearButton - Button to clear the search field
Label - Field label component from @lenso/ui
Description - Helper text component from @lenso/ui
FieldError - Validation error message from @lenso/ui

Each of these components has its own props API. Use them directly within SearchField for composition:

1<SearchField isRequired isInvalid={hasError} value={value} onChange={setValue}>2  <Label>Search</Label>3  <SearchField.Group>4    <SearchField.SearchIcon />5    <SearchField.Input placeholder="Search..." />6    <SearchField.ClearButton />7  </SearchField.Group>8  <Description>Enter keywords to search</Description>9  <FieldError>Search query is required</FieldError>10</SearchField>

SearchField.Group Props

SearchField.Group inherits props from React Aria's Group component.

Prop	Type	Default	Description
`children`	`React.ReactNode \| (values: GroupRenderProps) => React.ReactNode`	-	Child components (SearchIcon, Input, ClearButton) or render function.
`className`	`string \| (values: GroupRenderProps) => string`	-	CSS classes for styling.

SearchField.Input Props

SearchField.Input inherits props from React Aria's Input component.

Prop	Type	Default	Description
`className`	`string`	-	CSS classes for styling.
`variant`	`"primary" \| "secondary"`	`"primary"`	Visual variant of the input. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces.
`placeholder`	`string`	-	Placeholder text displayed when the input is empty.
`type`	`string`	`"search"`	Input type (automatically set to "search").

SearchField.SearchIcon Props

SearchField.SearchIcon is a custom component that renders the search icon.

Prop	Type	Default	Description
`children`	`React.ReactNode`	`<IconSearch />`	Custom icon element. Defaults to search icon.
`className`	`string`	-	CSS classes for styling.

SearchField.ClearButton Props

SearchField.ClearButton inherits props from React Aria's Button component.

Prop	Type	Default	Description
`children`	`React.ReactNode`	`<CloseButton icon />`	Icon or content for the button. Defaults to close icon.
`className`	`string`	-	CSS classes for styling.
`slot`	`"clear"`	`"clear"`	Must be set to "clear" (automatically set).

Render Props

When using render props with className, style, or children, these values are available:

Prop	Type	Description
`isDisabled`	`boolean`	Whether the field is disabled.
`isInvalid`	`boolean`	Whether the field is currently invalid.
`isReadOnly`	`boolean`	Whether the field is read-only.
`isRequired`	`boolean`	Whether the field is required.
`isFocused`	`boolean`	Whether the field is currently focused (DEPRECATED - use `isFocusWithin`).
`isFocusWithin`	`boolean`	Whether any child element is focused.
`isFocusVisible`	`boolean`	Whether focus is visible (keyboard navigation).
`value`	`string`	Current value.
`isEmpty`	`boolean`	Whether the field is empty.

See upstream SearchField showcases. Product showcases are not part of the local component runtime.

Label

Renders an accessible label associated with form controls

Description

Provides supplementary text for form fields and other components

FieldError

Displays validation error messages for form fields

SearchField

Usage

Anatomy

Examples

Variants

In Surface

With Description

Required Field

Disabled State

Full Width

Validation

Controlled

Form Example

With Validation

Custom Icons

With Keyboard Shortcut

Render Function

Customization

Tailwind CSS

Global CSS

Styling Reference

CSS Classes

Base Classes [!toc]

Variant Classes [!toc]

Interactive States

API Reference

SearchField

Base Props

Value Props

Validation Props

State Props

Form Props

Event Props

Accessibility Props

Composition Components

SearchField.Group Props

SearchField.Input Props

SearchField.SearchIcon Props

SearchField.ClearButton Props

Render Props

Related Showcases

Related Components