<!--
{
  "availability" : [
    "iOS: 13.0.0 -",
    "iPadOS: 13.0.0 -",
    "macCatalyst: 13.1.0 -",
    "visionOS: 1.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "UIKit",
  "identifier" : "/documentation/UIKit/UISearchTextField",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "UIKit"
    ],
    "preciseIdentifier" : "c:objc(cs)UISearchTextField"
  },
  "title" : "UISearchTextField"
}
-->

# UISearchTextField

A view for displaying and editing text and search tokens.

```
@MainActor class UISearchTextField
```

## Overview

Use a search text field to display search criteria represented as text and tokens, and allow the user to edit that criteria. Tokens are discrete representations of nontextual content that your app can create and use to represent filters that limit the search results. Tokens always occur contiguously before any text in the search field.

[`UISearchBar`](/documentation/UIKit/UISearchBar) hosts a search text field, but you may also use a search text field in other roles, such as the title view of a [`UINavigationItem`](/documentation/UIKit/UINavigationItem).

> Note:
> The search field assigns text positions (``doc://com.apple.uikit/documentation/UIKit/UITextPosition``) to tokens as well as text so that users can interact with tokens using selection gestures and keyboard input. If the current selection includes any tokens, ``doc://com.apple.uikit/documentation/UIKit/UITextInput/selectedTextRange`` includes their positions. Use the search field’s ``doc://com.apple.uikit/documentation/UIKit/UISearchTextField/textualRange`` property to access the range of just the text without the tokens.

Tokens can be programmatically selected by including their position in a range assigned to the [`selectedTextRange`](/documentation/UIKit/UITextInput/selectedTextRange) property.

## Topics

### Converting text into tokens

[`replaceTextualPortion(of:with:at:)`](/documentation/UIKit/UISearchTextField/replaceTextualPortion(of:with:at:))

Converts text in a search field into a search token.

[`textualRange`](/documentation/UIKit/UISearchTextField/textualRange)

The range of the field’s text content.

### Supporting token interactions

[`allowsDeletingTokens`](/documentation/UIKit/UISearchTextField/allowsDeletingTokens)

A Boolean that indicates whether the user can remove tokens from the search field.

[`allowsCopyingTokens`](/documentation/UIKit/UISearchTextField/allowsCopyingTokens)

A Boolean that indicates whether the user can copy or drag tokens from the search field.

[`delegate`](/documentation/UIKit/UITextField/delegate)

The text field’s delegate.

[`UISearchTextFieldDelegate`](/documentation/UIKit/UISearchTextFieldDelegate)

The interface for the delegate of a search field.

[`UISearchTextFieldPasteItem`](/documentation/UIKit/UISearchTextFieldPasteItem)

A protocol that supports pasting tokens.

### Adding and removing tokens

[`tokens`](/documentation/UIKit/UISearchTextField/tokens)

The collection of tokens in the search text field.

[`insertToken(_:at:)`](/documentation/UIKit/UISearchTextField/insertToken(_:at:))

Adds a search token at a specific index.

[`removeToken(at:)`](/documentation/UIKit/UISearchTextField/removeToken(at:))

Removes a particular search token from the search text field.

### Customizing token behavior

[`tokenBackgroundColor`](/documentation/UIKit/UISearchTextField/tokenBackgroundColor)

The background color for all tokens in the search text field.

[`tokens(in:)`](/documentation/UIKit/UISearchTextField/tokens(in:))

Returns the search field’s tokens that are within a given range.

[`positionOfToken(at:)`](/documentation/UIKit/UISearchTextField/positionOfToken(at:))

Converts a token index into a text position.

### Providing search suggestions

[`searchSuggestions`](/documentation/UIKit/UISearchTextField/searchSuggestions)

A list of suggestions to offer as shortcuts below the search field.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)