App Shortcuts Action button default parameter

Hello,

I have a question about App Intents and the Action button on iPhone.

I have an App Intent that opens the app and navigates to a specific entity, conforming to OpenIntent with a single AppEntity parameter. The entity conforms to EnumerableEntityQuery, and the intent is registered as an App Shortcut via the AppShortcutsProvider.

When assigning this shortcut to the Action button in Settings, the system doesn’t prompt the user to select a default entity upfront. Instead, it prompts on every activation, creating friction.

In contrast, shortcuts like “Open Note…” and other third-party ones prompt the user for a note to open when setting up the Action button, and its title also includes three dots, indicating a pre-configurable parameter. My shortcut’s title shows no dots.

What’s required to make an App Shortcut prompt for a default parameter during Action button setup?

Sincerely, Holger

Answered by DTS Engineer in 900059022

Thanks for describing the setup precisely, including the contrast with what you have seen on other shortcuts. That was enough to reproduce it here, and your reading of the ellipsis was right: the setup-time prompt is available.

What produces it is the parameterPresentation: argument on AppShortcut:

struct TestShortcuts: AppShortcutsProvider {
    static var appShortcuts: [AppShortcut] {
        AppShortcut(
            intent: OpenNoteIntent(),
            phrases: ["Open \(\.$target) in \(.applicationName)"],
            shortTitle: "Open Note",
            systemImageName: "note.text",
            parameterPresentation: ParameterPresentation(
                for: \.$target,
                summary: Summary("Open \(\.$target)"),
                optionsCollections: {
                    OptionsCollection(
                        NoteEntityQuery(),
                        title: "Notes",
                        systemImageName: "note.text"
                    )
                }
            )
        )
    }
}

ParameterPresentation, Summary, and OptionsCollection are typealiases visible inside an AppShortcutsProvider. Your existing query supplies the options collection directly, with no adapter: EnumerableEntityQuery refines EntityQuery, which refines DynamicOptionsProvider, and that last conformance is what OptionsCollection accepts.

I built two versions of a minimal project matching your setup, differing only in whether the App Shortcut carried parameterPresentation. Without it, the chooser entry has no ellipsis and the entity list appears on every activation. With it, the entry reads "Open Note…", selecting it requests the value immediately while still in the Action Button settings screen, and subsequent presses open the chosen entity with no further prompting.

Verified on an iPhone 16 running iOS 26.5.2.

Building a parameterized shortcut by hand in the Shortcuts app, as suggested earlier in the thread, also works, but based on what I measured it is not required to get the prompt you were after.

If you would rather have this reachable from Control Center and the Lock Screen as well, a Control is the other route: ControlWidgetButton has an initializer overload constrained to OpenIntent, and promptsForUserConfiguration() requests the value when the control is added. I measured that path too, with the same result. It requires iOS 18, where parameterPresentation is available from iOS 17.

References:

User can set the parameter in Shortcuts and save it as a name. If no parameter is provided it will prompt (let's say you have a Shortcut Control/Intent). Otherwise create an intent without a parameter and it will open to that page.

That's how I'd do it.

Yes, that would work, but still requires the user to create a specific intent with a prefilled parameter, rather than the system just asking for the parameter upfront when selecting the App Shortcut inside Action button settings.

Thanks for describing the setup precisely, including the contrast with what you have seen on other shortcuts. That was enough to reproduce it here, and your reading of the ellipsis was right: the setup-time prompt is available.

What produces it is the parameterPresentation: argument on AppShortcut:

struct TestShortcuts: AppShortcutsProvider {
    static var appShortcuts: [AppShortcut] {
        AppShortcut(
            intent: OpenNoteIntent(),
            phrases: ["Open \(\.$target) in \(.applicationName)"],
            shortTitle: "Open Note",
            systemImageName: "note.text",
            parameterPresentation: ParameterPresentation(
                for: \.$target,
                summary: Summary("Open \(\.$target)"),
                optionsCollections: {
                    OptionsCollection(
                        NoteEntityQuery(),
                        title: "Notes",
                        systemImageName: "note.text"
                    )
                }
            )
        )
    }
}

ParameterPresentation, Summary, and OptionsCollection are typealiases visible inside an AppShortcutsProvider. Your existing query supplies the options collection directly, with no adapter: EnumerableEntityQuery refines EntityQuery, which refines DynamicOptionsProvider, and that last conformance is what OptionsCollection accepts.

I built two versions of a minimal project matching your setup, differing only in whether the App Shortcut carried parameterPresentation. Without it, the chooser entry has no ellipsis and the entity list appears on every activation. With it, the entry reads "Open Note…", selecting it requests the value immediately while still in the Action Button settings screen, and subsequent presses open the chosen entity with no further prompting.

Verified on an iPhone 16 running iOS 26.5.2.

Building a parameterized shortcut by hand in the Shortcuts app, as suggested earlier in the thread, also works, but based on what I measured it is not required to get the prompt you were after.

If you would rather have this reachable from Control Center and the Lock Screen as well, a Control is the other route: ControlWidgetButton has an initializer overload constrained to OpenIntent, and promptsForUserConfiguration() requests the value when the control is added. I measured that path too, with the same result. It requires iOS 18, where parameterPresentation is available from iOS 17.

References:

App Shortcuts Action button default parameter
 
 
Q