Actions API revision

What changed?

In Flutter an `Intent` is an object that's typically bound to a keyboard key combination using the `Shortcuts` widget. An `Intent` can be bound to an `Action`, which can update the application's state or perform other operations. In the course of using this API, we identified several drawbacks in the design, so we have updated the Actions API to make it easier to use and understand.

Original behavior

The original Actions API design was oriented towards invoking actions from widgets, and having those actions act in the context of the widget. Teams have been using actions, and found several limitations in that design that needed to be addressed:

New behavior

Here are the changes made to address the above problems:

Will this affect my application?

Who is affected: Applications and packages relying on the previous behaviour or signature. Code that uses Intent, Shortcuts, Action and related APIs.
Practical impact: Behaviour or API differences that can break builds or change runtime behaviour.
What action should I take?: Follow the official migration guide below, update affected call sites, run `dart fix --apply` where a fix is available, then run your tests.

APIs mentioned:Intent Shortcuts Action LocalKey ActionFactory LogicalKeySet Type LocalKeys Actions FocusNode Action.invoke Actions.invoke

How do I migrate safely?

Before and after (from the official guide)

dart+3−3

Before

1		class MyWidget extends StatelessWidget {
2		// ...
3		@override
4		Widget build(BuildContext context) {
5		return Shortcuts(
6		shortcuts: <LogicalKeySet, Intent> {
7	−	LogicalKeySet(LogicalKeyboardKey.enter): Intent(ActivateAction.key),
8		},
9		child: Actions(
10	−	actions: <LocalKey, ActionFactory>{
11	−	Activate.key: () => ActivateAction(),
12		},
13		child: Container(),
14		)
15		);
16		}
17		}

After

1		class MyWidget extends StatelessWidget {
2		// ...
3		@override
4		Widget build(BuildContext context) {
5		return Shortcuts(
6		shortcuts: <LogicalKeySet, Intent> {
7	+	LogicalKeySet(LogicalKeyboardKey.enter): ActivateIntent,
8		},
9		child: Actions(
10	+	actions: <Type, Action<Intent>>{
11	+	ActivateIntent: ActivateAction(),
12		},
13		child: Container(),
14		)
15		);
16		}
17		}

Raw before / after

class MyWidget extends StatelessWidget {
  // ...
  @override
  Widget build(BuildContext context) {
    return Shortcuts(
      shortcuts: <LogicalKeySet, Intent> {
        LogicalKeySet(LogicalKeyboardKey.enter): Intent(ActivateAction.key),
      },
      child: Actions(
        actions: <LocalKey, ActionFactory>{
          Activate.key: () => ActivateAction(),
        },
        child: Container(),
      )
    );
  }
}

class MyWidget extends StatelessWidget {
  // ...
  @override
  Widget build(BuildContext context) {
    return Shortcuts(
      shortcuts: <LogicalKeySet, Intent> {
        LogicalKeySet(LogicalKeyboardKey.enter): ActivateIntent,
      },
      child: Actions(
        actions: <Type, Action<Intent>>{
          ActivateIntent: ActivateAction(),
        },
        child: Container(),
      )
    );
  }
}

Migration checklist0/2

Update the argument type of the actions argument
Use an instance of a specific Intent class in the

Official migration guide (excerpt, © The Flutter Authors, CC BY 3.0)

Significant changes area required to update existing code to the new API.

Actions mapping for pre-defined actions

To update the action maps in the Actions widget for predefined actions in Flutter, like ActivateAction and SelectAction, do the following:

Update the argument type of the actions argument
Use an instance of a specific Intent class in the Shortcuts mapping, rather than an Intent(TheAction.key) instance.

Code before migration:

class MyWidget extends StatelessWidget {
  // ...
  @override
  Widget build(BuildContext context) {
    return Shortcuts(
      shortcuts: &#x3C;LogicalKeySet, Intent> {
        LogicalKeySet(LogicalKeyboardKey.enter): Intent(ActivateAction.key),
      },
      child: Actions(
        actions: &#x3C;LocalKey, ActionFactory>{
          Activate.key: () => ActivateAction(),
        },
        child: Container(),
      )
    );
  }
}

Code after migration:

class MyWidget extends StatelessWidget {
  // ...
  @override
  Widget build(BuildContext context) {
    return Shortcuts(
      shortcuts: &#x3C;LogicalKeySet, Intent> {
        LogicalKeySet(LogicalKeyboardKey.enter): ActivateIntent,
      },
      child: Actions(
        actions: &#x3C;Type, Action&#x3C;Intent>>{
          ActivateIntent: ActivateAction(),
        },
        child: Container(),
      )
    );
  }
}

Custom actions

To migrate your custom actions, eliminate the LocalKeys you've defined, and replace them with Intent subclasses, as well as changing the type of the argument to the actions argument of the Actions widget.

Code before migration:

class MyAction extends Action {
  MyAction() : super(key);

  /// The [LocalKey] that uniquely identifies this action to an [Intent].
  static const LocalKey key = ValueKey&#x3C;Type>(RequestFocusAction);

  @override
  void invoke(FocusNode node, MyIntent intent) {
    // ...
  }
}

class MyWidget extends StatelessWidget {
  // ...
  @override
  Widget build(BuildContext context) {
    return Shortcuts(
      shortcuts: &#x3C;LogicalKeySet, Intent> {
        LogicalKeySet(LogicalKeyboardKey.enter): Intent(MyAction.key),
      },
      child: Actions(
        actions: &#x3C;LocalKey, ActionFactory>{
          MyAction.key: () => MyAction(),
        },
        child: Container(),
      )
    );
  }
}

Code after migration:

// You may need to create new Intent subclasses if you used
// a bare LocalKey before.
class MyIntent extends Intent {
  const MyIntent();
}

class MyAction extends Action&#x3C;MyIntent> {
  @override
  Object invoke(MyIntent intent) {
    // ...
  }
}

class MyWidget extends StatelessWidget {
  // ...
  @override
  Widget build(BuildContext context) {
    return Shortcuts(
      shortcuts: &#x3C;LogicalKeySet, Intent> {
        LogicalKeySet(LogicalKeyboardKey.enter): MyIntent,
      },
      child: Actions(
        actions: &#x3C;Type, Action&#x3C;Intent>>{
          MyIntent: MyAction(),
        },
        child: Container(),
      )
    );
  }
}

Custom `Actions` and `Intents` with arguments

To update actions that use intent arguments or hold state, you need to modify the arguments to the invoke method. In the example below, the code keeps the value of the argument in the intent as part of the action instance. This is because in the old design there is a new instance of the action created each time it's executed, and the resulting action could be kept by the [ActionDispatcher][] to record the state.

In the example of post migration code below, the new MyAction returns the state as the result of calling invoke, since a new instance isn't created for each invocation. This state is returned to the caller of Actions.invoke, or ActionDispatcher.invokeAction, depending on how the action is invoked.

Code before migration:

class MyIntent extends Intent {
  const MyIntent({this.argument});

  final int argument;
}

class MyAction extends Action {
  MyAction() : super(key);

  /// The [LocalKey] that uniquely identifies this action to an [Intent].
  static const LocalKey key = ValueKey&#x3C;Type>(RequestFocusAction);

  int state;

  @override
  void invoke(FocusNode node, MyIntent intent) {
    // ...
    state = intent.argument;
  }
}

Code after migration:

class MyIntent extends Intent {
  const MyIntent({this.argument});

  final int argument;
}

class MyAction extends Action&#x3C;MyIntent> {
  @override
  int invoke(Intent intent) {
    // ...
    return intent.argument;
  }
}

Migration assistantAI-generated · grounded in cited sources

AI explanations are not configured

Set AI_PROVIDER (for example to openai-compatible with a local Ollama or LM Studio endpoint) to enable grounded explanations. Everything else on this page works without an AI provider.

Evidence & verification

Official migration guide·Verified classification (95%)

Listed in the official breaking-changes index (docs.flutter.dev/release/breaking-changes).

An official announcement or migration guide documents an intended behaviour or API change. A verified source change (git diff) shows code changed but does not by itself prove a public API is breaking. AI interpretations are labelled and never used to classify a change.

Validation warnings

api-symbols: {"reason":"no referenced symbol found in the current API index","unresolved":["Intent","Shortcuts","Action","LocalKey","ActionFactory","LogicalKeySet","Type","LocalKeys","Actions","FocusNode","Action.invoke","Actions.invoke","CallbackAction","OnInvokeCallback","ActionDispatcher.invokeAction","BuildContext","Object","ActivateAction","SelectAction","Intents","ActionDispatcher","MyAction"]}

Source commit: b3045439b7c0
Source last updated: Oct 21, 2026
Last synchronized: Oct 21, 2026
Publication status: published

Publication history

Oct 21, 2026, 8:31 PM: new → published (ingestion) — Backed by an official breaking-change/migration guide.

AI explanationAI-generated · grounded in cited sources

AI explanations are not configured

Set AI_PROVIDER (for example to openai-compatible with a local Ollama or LM Studio endpoint) to enable grounded explanations. Everything else on this page works without an AI provider.

Was this useful?

BreakingHigh impactnot yet in stableandroid migration guide

Original behavior

New behavior

Before and after (from the official guide)

Actions mapping for pre-defined actions

Custom actions

Custom Actions and Intents with arguments

Custom `Actions` and `Intents` with arguments