Home › Articles › skipTraversal on FocusableActionDetector

skipTraversal on FocusableActionDetector: the story of Flutter PR #191308, by Ishaq Hassan

Five Lines, Two Attempts: Bringing skipTraversal to FocusableActionDetector

A widget that could take focus but could not be skipped in Tab order. An earlier fix that stalled. And the second attempt that the Flutter 3.50 release blog ended up naming.

Shipped: skipTraversal on FocusableActionDetector is in stable Flutter 3.50.0, released November 11, 2026. The official Flutter 3.50 release blog names me for it in its accessibility and navigation section, and the 3.50.0 release notes credit #191308.

PR #191308 merged into Flutter on September 3, 2026. The library change is five lines in actions.dart and two documentation lines in focus_scope.dart. The test is 75 lines. It took about fifteen days from opening to merge.

The interesting part is not the size. It is that this was the second pull request for the same issue. The first one was reasonable, picked up two approvals, and was still closed. This article is about why, what I changed, what review asked for, and how to use the parameter now that it is in stable.

The gap: one parameter that did not get forwarded

FocusableActionDetector is the convenience widget for building your own interactive control. It bundles Focus, Shortcuts, Actions and MouseRegion, so a custom button or tile gets focus handling, keyboard shortcuts, hover and focus highlights in one place.

Inside, it builds a Focus widget and forwards a set of focus options to it: focusNode, autofocus, descendantsAreFocusable and descendantsAreTraversable. One option on that inner Focus was never forwarded: skipTraversal.

skipTraversal is a precise tool. A node with it set can still be focused, and it can still receive key events as part of the focus chain. The only thing it gives up is being visited by the focus traversal policy, which in practice means the Tab key. Focus has supported it for years. FocusableActionDetector simply had no way to pass it through, so the only workaround was to copy the whole widget.

Issue #187093, opened on May 26, 2026, asked for exactly that: expose skipTraversal and forward it.

Why Tab order matters

For a keyboard user, every focusable widget is a stop. Picture a chat screen with fifty message bubbles that can each be focused so they can take a copy shortcut. Without a way to skip them, the message field at the bottom is fifty Tab presses away. Making the bubbles unfocusable is not the answer either, because then a tap cannot focus them and their shortcuts stop working.

What you want is the middle ground: focusable on request, absent from Tab order. That is what skipTraversal means, and that is why the 3.50 release blog put this change under accessibility.

The first attempt stalled

A community pull request for the issue, #187356, opened on May 31. It forwarded the parameter, and it picked up approvals from two reviewers in June. But it also bundled some unrelated private named parameter changes, and those drew review comments that went unanswered. In July a maintainer closed it, with a note that a new patch would be welcome.

Nothing was wrong with the idea. The pull request carried more than the issue needed, and then it went quiet. That happens to everyone with a day job. It also means the issue was still open, with a maintainer who had already said yes in principle.

A closed pull request with an approval and an invitation to resubmit is one of the best starting points a contributor can find. The design question has already been answered.

The second attempt: the five lines and nothing else

I opened #191308 on August 18 (UTC), and the description says up front that it revives #187356 and why it is smaller. Everything unrelated is gone. What is left is the forwarding:

// packages/flutter/lib/src/widgets/actions.dart
const FocusableActionDetector({
  // ...
  this.descendantsAreTraversable = true,
  this.skipTraversal,
  // ...
});

/// {@macro flutter.widgets.Focus.skipTraversal}
final bool? skipTraversal;

// in _FocusableActionDetectorState.build:
Focus(
  // ...
  descendantsAreTraversable: widget.descendantsAreTraversable,
  skipTraversal: widget.skipTraversal,
  // ...
)

Two small decisions carry the whole design:

  • It is bool?, not bool. Focus.skipTraversal takes a nullable value, and null means "use the focus node's own setting, or false". Matching that type means the default changes nothing for any existing caller, and a focus node you pass in keeps control unless you say otherwise.
  • The documentation is shared, not copied. The existing doc comment on Focus.skipTraversal is wrapped in a {@template flutter.widgets.Focus.skipTraversal} block, and the new field pulls it in with {@macro}. That is the convention the same widget already uses for descendantsAreFocusable and descendantsAreTraversable, so the two extra lines in focus_scope.dart are the template markers.

The review: one bot, two maintainers, fifteen days

The first review arrived within two minutes, from gemini-code-assist, the AI reviewer that does a first pass on Flutter pull requests. It suggested adding skipTraversal to debugFillProperties so it would show up in DevTools.

I said no, and explained why. FocusableActionDetector does not override debugFillProperties at all. Adding an override just for this one property would leave the widget's other thirteen properties out of the diagnostics tree, which is worse than the current consistent state, and it was outside the scope of the issue. I offered a separate pull request that fills diagnostics in for the whole widget. A bot suggestion is a suggestion. The useful response is a reason, not automatic compliance.

Then the humans. Renzo-Olivares asked for one thing: a test that proves the traversal actually skips the detector, not just that the value reaches the inner Focus. Fair point. My first test checked forwarding, which is necessary but not sufficient.

So I added a behavior test. It puts the detector between two buttons, focuses the first, calls nextFocus() and asserts that focus lands on the second button instead of the detector. Then it checks the part that makes skipTraversal different from canRequestFocus: the detector can still be focused explicitly.

Before pushing, I removed the forwarding line from actions.dart and ran the test again. It failed. A test that still passes when you delete the fix is not testing the fix, and running that check takes thirty seconds.

Pushing the new commits reset an earlier review, so the change needed fresh approvals. Renzo-Olivares approved on September 1, victorsanni approved on September 2, and the auto-submit bot merged it on September 3. About fifteen days end to end, against 75 for my RawImage blendMode change.

Use it today: Flutter 3.50.0 and later

The parameter is in stable since Flutter 3.50.0. On older SDKs the argument does not exist and this code will not compile, so run flutter upgrade first. Here is the chat bubble from earlier as a complete widget: a tap focuses it, Ctrl+C or Cmd+C copies the message, and Tab moves straight past it.

import 'package:flutter/services.dart';
import 'package:flutter/widgets.dart';

class CopyMessageIntent extends Intent {
  const CopyMessageIntent();
}

/// A chat bubble that a tap can focus, so it can take a copy shortcut,
/// without becoming one more Tab stop in a long conversation.
class MessageBubble extends StatefulWidget {
  const MessageBubble({super.key, required this.text});

  final String text;

  @override
  State<MessageBubble> createState() => _MessageBubbleState();
}

class _MessageBubbleState extends State<MessageBubble> {
  final FocusNode _focusNode = FocusNode(debugLabel: 'MessageBubble');
  bool _focused = false;

  @override
  void dispose() {
    _focusNode.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return FocusableActionDetector(
      focusNode: _focusNode,
      skipTraversal: true, // Flutter 3.50.0 and later
      onFocusChange: (bool focused) => setState(() => _focused = focused),
      shortcuts: const <ShortcutActivator, Intent>{
        SingleActivator(LogicalKeyboardKey.keyC, control: true):
            CopyMessageIntent(),
        SingleActivator(LogicalKeyboardKey.keyC, meta: true):
            CopyMessageIntent(),
      },
      actions: <Type, Action<Intent>>{
        CopyMessageIntent: CallbackAction<CopyMessageIntent>(
          onInvoke: (CopyMessageIntent intent) =>
              Clipboard.setData(ClipboardData(text: widget.text)),
        ),
      },
      child: GestureDetector(
        onTap: _focusNode.requestFocus,
        child: DecoratedBox(
          decoration: BoxDecoration(
            color: const Color(0xFF1E1E1E),
            borderRadius: BorderRadius.circular(12),
            border: Border.all(
              color: _focused
                  ? const Color(0xFF7DD3FC)
                  : const Color(0x1FFFFFFF),
            ),
          ),
          child: Padding(
            padding: const EdgeInsets.all(12),
            child: Text(widget.text),
          ),
        ),
      ),
    );
  }
}

I checked this with flutter analyze against a framework build that includes #191308, and with a widget test: Tab from the widget before the bubble lands on the widget after it, a tap gives the bubble primary focus, and Ctrl+C puts the text on the clipboard. With skipTraversal switched back to false, the Tab assertion fails, so the test is measuring the right thing.

skipTraversal, canRequestFocus or descendantsAreTraversable?

Flutter has several focus switches that sound alike. They do different jobs:

  • skipTraversal: true: not a Tab stop, but it can still be focused on request and still handles key events while focused.
  • canRequestFocus: false: cannot take focus at all, so no keyboard shortcuts through the focus chain either.
  • descendantsAreTraversable: false: everything below this widget is skipped by traversal, while the widget itself can still be a stop.
  • descendantsAreFocusable: false, or wrapping in ExcludeFocus: nothing below this widget can take focus at all.

One more detail I checked in the framework source: the semantics that Focus adds follow canRequestFocus, not skipTraversal. So a skipped widget stays focusable for screen readers. Only keyboard traversal changes.

Use it with care

Skipping a widget in Tab order is an accessibility decision, not just a convenience. A keyboard-only user can no longer reach that widget by tabbing, so whatever it does must be reachable another way. In the chat example, that could be a message menu button that is a normal Tab stop, or a shortcut on the list itself. Use skipTraversal to remove redundant stops, not to hide the only path to an action.

The playbook for reviving a stalled pull request

  1. Read the closing note. A maintainer who writes "a new patch would be welcome" has already approved the idea.
  2. Credit and link the original. Say in the description which pull request you are reviving and what you changed. Reviewers remember context, and it is simply the right thing to do.
  3. Trim to the issue. Whatever drew the unanswered comments is usually the part the issue never asked for.
  4. Match the house conventions. Same nullable type as the inner widget, same template and macro pattern as the neighboring properties.
  5. Answer every review with a reason, including the bot's. Agreeing is fine, declining is fine, silence is what stalls pull requests.
  6. Prove the test catches the bug. Remove the fix, watch the test fail, put the fix back.

If you want the longer version of how I pick and land framework changes from Karachi, it is in my first contribution playbook, and the full list of what shipped in 3.50 is in 13 of my commits in Flutter 3.50.


Want to land your first Flutter framework PR?

I mentor engineers on exactly this path: finding the right first issue, surviving review, and building a contribution track record. 13+ years of engineering, 15 technical PRs merged across Flutter and DevTools, and the scars to prove the queue is survivable.

Get in touch →

FAQ

What does skipTraversal do on FocusableActionDetector?

It sets FocusNode.skipTraversal on the detector's inner Focus, so Tab-key traversal moves past the widget. It can still be focused explicitly, and its shortcuts and actions still work while it has focus. The default, null, keeps the old behavior.

Which Flutter version has skipTraversal on FocusableActionDetector?

Stable Flutter 3.50.0, released November 11, 2026, and every later release. Earlier versions do not have the argument.

What is the difference between skipTraversal and canRequestFocus?

canRequestFocus: false makes a widget unable to take focus at all. skipTraversal: true only removes it from Tab-key traversal: it can still be focused on request and still handle shortcuts.

Does skipTraversal hide a widget from screen readers?

No. The semantics that Focus adds follow canRequestFocus, so the widget stays focusable for assistive technology. Keyboard-only users cannot Tab to it, so make its action reachable another way.

How long did PR #191308 take to merge?

About fifteen days: opened August 18, 2026 (UTC), approved on September 1 and 2, merged on September 3.


Also published on:

Dev.to Medium

Source of record:

PR #191308 on GitHub Issue #187093 The earlier PR, #187356 What's new in Flutter 3.50

Related reading

Ishaq Hassan is a Flutter Framework Contributor with 15 technical PRs merged across Flutter and DevTools, listed in the official Flutter AUTHORS file, Engineering Manager at DigitalHire, and creator of the 35-video Urdu Flutter course listed on docs.flutter.dev. Karachi, Pakistan. ishaqhassan.dev.