Search field

iOSAndroidTry it (web)

iPhone 17 Pro · iOS 27

Copy Text

import Cancel01Icon from "@hugeicons-pro/core-bulk-rounded/Cancel01Icon";
import Search01Icon from "@hugeicons-pro/core-bulk-rounded/Search01Icon";
import { HugeiconsIcon } from "@hugeicons/react-native";
import { SearchField } from "@terratcg/ui";
import { useState } from "react";

export default function SearchFieldDefault() {
  const [query, setQuery] = useState("Red fox");
  return (
    <SearchField
      value={query}
      onChangeText={setQuery}
      placeholder="Search your library"
      clearLabel="Clear search"
      icon={({ color, size }) => <HugeiconsIcon icon={Search01Icon} color={color} size={size} />}
      clearIcon={({ color, size }) => <HugeiconsIcon icon={Cancel01Icon} color={color} size={size} />}
      containerStyle={{ alignSelf: "stretch" }}
    />
  );
}

ImportCopy Anchor Link

import { SearchField } from "@terratcg/ui";

UsageCopy Anchor Link

<SearchField
  value={query}
  onChangeText={setQuery}
  placeholder="Search your library"
  clearLabel="Clear search"
  icon={({ color, size }) => <SearchIcon color={color} size={size} />}
  clearIcon={({ color, size }) => <CloseIcon color={color} size={size} />}
/>

SearchField is a controlled Input: value and onChangeText are required. The icons come from you, as nodes or as render functions given the colour and size to draw in. The screen around it owns the rest: the results, the filtering and any Cancel link.

ExamplesCopy Anchor Link

DisabledCopy Anchor Link

A disabled search field takes no input and offers no clear key, even with text in it.

iOSAndroidTry it (web)

iPhone 17 Pro · iOS 27

Copy Text

import Cancel01Icon from "@hugeicons-pro/core-bulk-rounded/Cancel01Icon";
import Search01Icon from "@hugeicons-pro/core-bulk-rounded/Search01Icon";
import { HugeiconsIcon } from "@hugeicons/react-native";
import { SearchField } from "@terratcg/ui";

export default function SearchFieldDisabled() {
  return (
    <SearchField
      disabled
      value="Red fox"
      onChangeText={() => {}}
      placeholder="Search your library"
      clearLabel="Clear search"
      icon={({ color, size }) => <HugeiconsIcon icon={Search01Icon} color={color} size={size} />}
      clearIcon={({ color, size }) => <HugeiconsIcon icon={Cancel01Icon} color={color} size={size} />}
      containerStyle={{ alignSelf: "stretch" }}
    />
  );
}

PropsCopy Anchor Link

SearchField also accepts the Input props except the adornments and the end slot, which it fills itself. It sets returnKeyType="search", autoCapitalize="none" and autoCorrect={false}; pass your own to change them.

AccessibilityCopy Anchor Link

• Name: accessibilityLabel if you pass one, else the placeholder. Inside a Field, the Label names it only when there is neither.
• Clear key: an Icon button named by clearLabel. It only appears while there is text, and pressing it empties the field and puts the caret back in it.
• Magnifier: visual only, hidden from screen readers.
• Disabled: no clear key, even with text in the field.

Platform differencesCopy Anchor Link

• Keyboard: the return key reads Search on both platforms; its label and look are each keyboard's own.
• Clear key: drawn the way the system draws it, on iOS and Android alike: a 22 point grey disc (Ink Muted at half strength) with the X cut out in the well's floor colour, centred in the field.
• Web: SearchField renders through react-native-web for these docs, but the web is not a supported target.

RulesCopy Anchor Link

• Keep value in your state, and run the search from onChangeText or onSubmitEditing.
• Always pass clearLabel, in the user's language.
• Draw the magnifier and the X from your app's own icons (icon, clearIcon); TerraUI ships no glyphs.
• Write the placeholder as what can be searched ("Search your library"), since it is also the field's name.
• Put any Cancel link next to the field, outside it.