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

# UIPhotoSearchSuggestion

An input suggestion that carries photo search metadata for people, subjects, locations, and time periods.

```
class UIPhotoSearchSuggestion
```

## Discussion

When someone types text that could match a photo library search, such as “photos from Paris last summer,” the system recognizes the input as a photo library search and delivers a `UIPhotoSearchSuggestion` through the [`textField(_:insertInputSuggestion:)`](/documentation/UIKit/UITextFieldDelegate/textField(_:insertInputSuggestion:)) or [`textView(_:insertInputSuggestion:)`](/documentation/UIKit/UITextViewDelegate/textView(_:insertInputSuggestion:)) delegate method. Use `as? UIPhotoSearchSuggestion` to check whether the incoming [`UIInputSuggestion`](/documentation/UIKit/UIInputSuggestion) is a photo search suggestion and access its metadata.

After receiving a suggestion, you have two options: Pass the object directly to the <doc://com.apple.documentation/documentation/Photos> framework to present a pre-populated photo picker, or read the `whoValues`, `whatValues`, `whereValues`, and `whenValues` arrays to build a custom search experience.

You can’t create a `UIPhotoSearchSuggestion` directly. The system creates and delivers instances through the input suggestion system.

### Presenting a photo picker

Pass the suggestion to `PHPickerSearchText(photoSearchSuggestion:)` to pre-populate a `PHPickerViewController` with photos matching the person’s search.

```swift
class SearchViewController: UIViewController, UITextFieldDelegate, PHPickerViewControllerDelegate {
    @IBOutlet var searchField: UITextField!

    func textField(_ textField: UITextField,
                   insertInputSuggestion inputSuggestion: UIInputSuggestion) {
        if let photoSuggestion = inputSuggestion as? UIPhotoSearchSuggestion {
            presentPhotosPicker(with: photoSuggestion)
        }
    }

    func presentPhotosPicker(with suggestion: UIPhotoSearchSuggestion) {
        var configuration = PHPickerConfiguration()
        configuration.searchText = PHPickerSearchText(photoSearchSuggestion: suggestion)
        let picker = PHPickerViewController(configuration: configuration)
        picker.delegate = self
        present(picker, animated: true)
    }

    func picker(_ picker: PHPickerViewController,
                didFinishPicking results: [PHPickerResult]) {
        dismiss(animated: true)
        // Handle selected photos.
    }
}
```

### Building a custom search

If your app has its own photo search UI, read the filter arrays and construct your own query.

```swift
func textField(_ textField: UITextField,
               insertInputSuggestion inputSuggestion: UIInputSuggestion) {
    guard let suggestion = inputSuggestion as? UIPhotoSearchSuggestion else { return }

    // Build a custom query from the individual filter values.
    let who = suggestion.whoValues        // e.g., ["John"]
    let what = suggestion.whatValues      // e.g., ["hiking"]
    let locations = suggestion.whereValues // e.g., ["Paris"]
    let timeframes = suggestion.whenValues // e.g., ["last summer"]

    performCustomPhotoSearch(people: who, subjects: what, locations: locations, timeframes: timeframes)
}
```

## Topics

### Instance Properties

[`var whatValues: [String]`](/documentation/UIKit/UIPhotoSearchSuggestion/whatValues)

Subjects or topics mentioned in the text that can be used to filter photos.

[`var whenValues: [String]`](/documentation/UIKit/UIPhotoSearchSuggestion/whenValues)

Time periods mentioned in the text that can be used to filter photos.

[`var whereValues: [String]`](/documentation/UIKit/UIPhotoSearchSuggestion/whereValues)

Locations mentioned in the text that can be used to filter photos.

[`var whoValues: [String]`](/documentation/UIKit/UIPhotoSearchSuggestion/whoValues)

People mentioned in the text that can be used to filter photos.

## Relationships

### Conforms To

[`CustomStringConvertible`](/documentation/Swift/CustomStringConvertible)

[`SendableMetatype`](/documentation/Swift/SendableMetatype)

[`CVarArg`](/documentation/Swift/CVarArg)

[`Sendable`](/documentation/Swift/Sendable)

[`NSObjectProtocol`](/documentation/ObjectiveC/NSObjectProtocol)

[`CustomDebugStringConvertible`](/documentation/Swift/CustomDebugStringConvertible)

[`Equatable`](/documentation/Swift/Equatable)

[`Hashable`](/documentation/Swift/Hashable)

### Inherits From

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

---

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)