<!--
{
  "documentType" : "article",
  "framework" : "AppIntents",
  "identifier" : "/documentation/AppIntents/Adding-parameters-to-an-app-intent",
  "metadataVersion" : "0.1.0",
  "role" : "article",
  "title" : "Adding parameters to an app intent"
}
-->

# Adding parameters to an app intent

Enable people to configure app intents with their custom input values.

## Overview

Many of your app’s actions likely require input data to perform their work. To help people provide the input that an [`AppIntent`](/documentation/AppIntents/AppIntent) needs to perform its functionality, add parameters to the intent to tell the system about that data and whether it’s required or optional. When you expose these parameters, people can configure your intents with values unique to their requirements and enable the App Intents framework to mediate with system experiences to write those values at runtime.

For example, the [Accelerating app interactions with App Intents](/documentation/AppIntents/AcceleratingAppInteractionsWithAppIntents) sample code project’s `GetTrailInfo` intent lets people choose which hiking trail information to view when they invoke the app intent. It declares a `trail` parameter by decorating the `trail` property with the [`IntentParameter`](/documentation/AppIntents/IntentParameter) property wrapper and provides a title and a description to identify the parameter in the Shortcuts app.

```swift
@Parameter(title: "Trail", description: "The trail to get information on.")
var trail: TrailEntity
```

Note that the example doesn’t provide localized text for the `title` and `description` fields to keep the example focused and make it easy to understand. Always provide localized strings for app intents, App Shortcuts, and their parameters.

### Make a parameter optional or required

How you define your parameter variables determines whether the system treats
that parameter as required or optional. If you define a variable as a
non-optional type, the system knows the parameter is required and, when
necessary, requests a value. Conversely, if you define a variable as an
optional type, the system assumes the parameter is optional and doesn’t request
a value. In this scenario, pause the intent and request a value when the intent can’t otherwise proceed by throwing the
property wrapper’s [`needsValueError(_:)`](/documentation/AppIntents/IntentParameter/needsValueError(_:)).

```swift
guard let date = date else {
    throw $date.needsValueError("What date would you like to use?")
}
```

### Define parameters using only the supported types

For every parameter you add to your app intent, choose only types that the App Intents framework supports. The
system needs to know how to handle your chosen types because it customizes interactions based on
those types. The following table lists the supported types.

|Category                   |Types                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |Notes                                                                                                                                            |
|---------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|
|Primitive value types      |<doc://com.apple.documentation/documentation/Swift/Bool>, <doc://com.apple.documentation/documentation/Swift/Int>, <doc://com.apple.documentation/documentation/Swift/Double>, <doc://com.apple.documentation/documentation/Swift/String>, <doc://com.apple.documentation/documentation/Foundation/AttributedString>, <doc://com.apple.documentation/documentation/Swift/Duration>, <doc://com.apple.documentation/documentation/Foundation/Date>, <doc://com.apple.documentation/documentation/Foundation/Decimal>, <doc://com.apple.documentation/documentation/Foundation/Measurement>, and <doc://com.apple.documentation/documentation/Foundation/URL>|None                                                                                                                                             |
|Collection types           |<doc://com.apple.documentation/documentation/Swift/Array>, <doc://com.apple.documentation/documentation/Swift/Set>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |Make sure the collection’s elements are of a type that’s compatible with ``doc://com.apple.AppIntents/documentation/AppIntents/IntentParameter``.|
|App Intents framework types|``doc://com.apple.AppIntents/documentation/AppIntents/EntityCollection``, ``doc://com.apple.AppIntents/documentation/AppIntents/IntentPerson``, ``doc://com.apple.AppIntents/documentation/AppIntents/IntentFile``, ``doc://com.apple.AppIntents/documentation/AppIntents/IntentCurrencyAmount``, ``doc://com.apple.AppIntents/documentation/AppIntents/IntentPaymentMethod``, ``doc://com.apple.AppIntents/documentation/AppIntents/SystemShortcut``, ``doc://com.apple.AppIntents/documentation/AppIntents/UnionValue()``                                                                                                                                |For additional information, see <doc://com.apple.AppIntents/documentation/AppIntents/common-data-types>.                                         |
|Other system types         |<doc://com.apple.documentation/documentation/MediaIntents/AudioSearch>, <doc://com.apple.documentation/documentation/Foundation/DateComponents>, <doc://com.apple.documentation/documentation/LinkPresentation/LinkMetadata>, <doc://com.apple.documentation/documentation/Foundation/PersonNameComponents>, <doc://com.apple.documentation/documentation/Photos/PHAsset>, <doc://com.apple.documentation/documentation/GeoToolbox/PlaceDescriptor>, <doc://com.apple.documentation/documentation/Foundation/Calendar/RecurrenceRule>, <doc://com.apple.documentation/documentation/VisualIntelligence/SemanticContentDescriptor>                          |None                                                                                                                                             |
|Custom app data            |``doc://com.apple.AppIntents/documentation/AppIntents/AppEntity``, ``doc://com.apple.AppIntents/documentation/AppIntents/AppEnum``                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |Use these types to store app-specific data.                                                                                                      |

> Note: App intent results support the same set of types.

When you want to specify app-specific data in a parameter, create an [`AppEntity`](/documentation/AppIntents/AppEntity) or [`AppEnum`](/documentation/AppIntents/AppEnum) type and use it to specify
your data. Apps make their app entities findable using queries, and the system can use those same queries to
resolve parameters that contain entities. Similarly, app enums provide a static set of options from which to choose, making
it easier for the system to identify possible values.

### Transform input into your intent parameter’s types

When a person provides input that your app intents use, the input doesn’t
always match the type that your parameters require. For example, natural spoken language
commands from Siri are strings, but your app intent might require an integer or
floating-point value. To help you with input of various types, use [Resolvers](/documentation/AppIntents/resolvers) to leverage the system’s ability to translate one type to another automatically so your app intent can use the input.

### Restrict parameter values

To make it easy for people to provide your app intents with the right information, restrict parameter values. The system presents known values as a list and prompts the person to
select one when it needs to resolve a parameter. To restrict parameter values to a list of known values:

- At compile time, use an enumeration type for the parameter that conforms to the [`AppEnum`](/documentation/AppIntents/AppEnum) protocol.
- At runtime, specify an options provider as part of the property wrapper’s declaration. An *options provider* is a type you implement that conforms to the [`DynamicOptionsProvider`](/documentation/AppIntents/DynamicOptionsProvider) protocol and provides a set of permitted values at runtime.

For example, the [Accelerating app interactions with App Intents](/documentation/AppIntents/AcceleratingAppInteractionsWithAppIntents) sample code project uses a dynamic options provider to display a sorted list of location parameters in the Shortcuts app.

```swift
struct LocationOptionsProvider: DynamicOptionsProvider {
    
    @Dependency
    private var trailManager: TrailDataManager
    
    func results() async throws -> [String] {
        Logger.intentLogging.debug("Getting locations from LocationOptionsProvider")
        
        // Get a list of locations and return it sorted for display, such as in the Shortcuts app.
        return trailManager.uniqueLocations
                .sorted(using: KeyPathComparator(\.self, comparator: .localizedStandard))
    }
}
```

You can configure a parameter with additional options such as enforcing an
inclusive range for number types, or specifying the capitalization style and
keyboard mode for string types. For more information, see [`IntentParameter`](/documentation/AppIntents/IntentParameter).

### Provide an interactive parameter summary for your intent

A parameter summary is a visual, textual outline of your app intent that the
Shortcuts app displays in the shortcut editor. The summary can include
placeholders that people interact with to choose the values for the intent’s
parameters. Even if your intent doesn’t expose any
parameters, providing a summary is an opportunity to present more information
about your intent in addition to its title.

To add a parameter summary to your intent, implement the protocol’s
[`parameterSummary`](/documentation/AppIntents/AppIntent/parameterSummary) requirement and use the provided [`ParameterSummaryBuilder`](/documentation/AppIntents/ParameterSummaryBuilder) result
builder to build the summary. Write the content using localized
natural language and, where applicable, substitute words that represent
parameters with the key paths to those parameters.

```swift
static var parameterSummary: some ParameterSummary {
        Summary("Get information on \(\.$trail)")
    }
```

The shortcut editor substitutes each key path with the corresponding
parameter’s title and enables a person to set the value by tapping it. The editor
uses the parameter’s type to determine which input controls to display.

Parameter summaries can include conditional statements such as
[`AppIntent.When`](/documentation/AppIntents/AppIntent/When) and [`AppIntent.Switch`](/documentation/AppIntents/AppIntent/Switch) that let the summary update itself
in response to already chosen values.

For example, the [Accelerating app interactions with App Intents](/documentation/AppIntents/AcceleratingAppInteractionsWithAppIntents) sample code project uses [`AppIntent.Switch`](/documentation/AppIntents/AppIntent/Switch) in its `SuggestedTrails` app intent:

```swift
    static var parameterSummary: some ParameterSummary {
        Switch(\.$activity) {
            Case(.biking) {
                When(\.$location, .hasAnyValue) {
                    Summary("Ride a bike within \(\.$searchRadius) of \(\.$location)")
                } otherwise: {
                    When(\.$trailCollection, .hasAnyValue) {
                        Summary("Pick a bike ride from \(\.$trailCollection)")
                    } otherwise: {
                        Summary("Suggest bike rides from \(\.$trailCollection) or near \(\.$location)")
                    }
                }
            }
            DefaultCase() {
                When(\.$location, .hasAnyValue) {
                    Summary("Suggest \(\.$activity) trails within \(\.$searchRadius) of \(\.$location)")
                } otherwise: {
                    When(\.$trailCollection, .hasAnyValue) {
                        Summary("Suggest \(\.$activity) trails from \(\.$trailCollection)")
                    } otherwise: {
                        Summary("Suggest \(\.$activity) trails from \(\.$trailCollection) or near \(\.$location)")
                    }
                }
            }
        }
    }
```

### Review the role of app entities

App entities provide the system with information about your app’s data, or
about concepts related to your app’s data. App entities describe your app’s custom data types you use for parameters, and help the system resolve parameters for app intents by letting it inspect relevant types. For example, a photo app that provides app entities for its photos and albums might also provide app entities to represent “the most recent photo” or “the default album.” These specific app entities help resolve intents more quickly and with fewer verbal interactions.

Define app entities for core types and concepts that you want to make available
to system experiences, and make sure to include properties for any data values that help people discover the entities using queries. For example, create an entity that describes a photo album and add a property to the entity for the name of the photo album.

For more information about expressing your app’s data as entities, see [Defining app entities for your custom data types](/documentation/AppIntents/defining-app-entities-for-your-custom-data-types).

---

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)