Skip to content

feat: add MD3 keyboard focus indicators - #5107

Merged
Doberjohn merged 51 commits into
callstack:mainfrom
k0ndee:@k0ndee/focus-indicators
Nov 16, 2026
Merged

Doberjohn merged 51 commits into
callstack:mainfrom
k0ndee:@k0ndee/focus-indicators

Conversation

@k0ndee

@k0ndee k0ndee commented Sep 7, 2026 •

Copy link
Copy Markdown
Contributor

Motivation

Most components had no keyboard focus indicator, and FAB, Checkbox and Switch each drew their own. This adds one shared MD3 ring (3dp, 2dp offset, secondary, keyboard only) on web and Android. Details and more screenshots are in a comment.

Related issue

Fixes #5083. Supersedes #5084.

Screenshots / Videos

Tab focus main This PR
Web Button
Android Chip close

Test plan

On web (Chrome) and Android (hardware keyboard), Tab through each component: the ring shows on keyboard focus only, not after a click or touch. iOS shows no ring.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

@k0ndee
k0ndee force-pushed the @k0ndee/focus-indicators branch from e1f7d10 to 737b751 Compare September 23, 2026 08:25
@Doberjohn Doberjohn added this to the 6.0.0 milestone Oct 30, 2026
@Doberjohn Doberjohn added the needs pickup Work that has been started but needs someone to pick it up and continue. label Nov 6, 2026
@Doberjohn Doberjohn removed the needs pickup Work that has been started but needs someone to pick it up and continue. label Nov 6, 2026
@Doberjohn Doberjohn modified the milestones: 6.0.0, 6.0.0-beta.0 Nov 12, 2026
lukemorawski and others added 13 commits November 13, 2026 13:49
The snapshots carried over from the pre-rebase commit didn't account for
the per-component hitSlop changes now merged in from 48dp-touch-targets.
Tabs fill the bar edge to edge and the bar clips (`overflow: 'hidden'`),
so the default outward ring lost its top and bottom and showed only as
vertical lines between tabs. Pass `focusRing: 'inward'` to
`renderTouchable` and forward it explicitly in the default `Touchable`
so it does not leak to the iOS `Pressable` fallback.
MD3 and Material Web ring chips outward (3dp, 2dp gap). The chip body was
inward so a scrolling chip row could not trim it, but that clip belongs to
the app's container, not to the chip, so the chip follows the spec.
Material Web rings the remove button with a circle around the icon. The
ring was a rounded rectangle around the whole 34dp close column from callstack#5108,
reaching the label. Focus still lands on the column, so its touch target is
unchanged; the ring is drawn outward on a 24dp circle (4/3 of the 18dp
icon, like Material Web) inside it, through the 'descendant' scope.
Checkbox.Item is a full-width row, like List.Item and RadioButton.Item,
which already ring inward. An outward ring ran into the rows above and
below it.
List.Accordion is a full-width row like List.Item, which already rings
inward, so the two were inconsistent and the accordion's outward ring ran
into the rows around it.
Menu items fill the menu's scroll view edge to edge with no gap between
them, so an outward ring was clipped by the menu and ran into the
neighbouring items. Material Web rings menu items inward too.
@Doberjohn

Doberjohn commented Nov 15, 2026 •

Copy link
Copy Markdown
Collaborator

Details that don't fit the description:

  • Where the ring goes: outward by default, as in MD3 and Material Web. Inward where an outward ring would be clipped or run into a neighbour: list and menu rows, Checkbox.Item, RadioButton.Item, Drawer.Item, FAB.Menu items, BottomNavigation tabs, DataTable rows, cells and titles, and SegmentedButtons. Drawer.CollapsedItem gets a rounded rectangle around its icon and label.
  • API: TouchableRipple takes a new focusRing prop (outward, inward or none), and so do the components built on its props. A component's theme prop sets its ring color.
  • Platforms: one hook, src/utils/useFocusRing.ts. Web uses CSS :focus-visible, Android tracks focus and sets outline* styles, and iOS shows no ring.
  • For apps: the "Focus indicator" section of the migration guide covers clipped rings and the focusRing prop.
More screenshots (taken before the latest review fixes)

Web (on main most components only get the browser's default outline):

Before After
Button before-web-button after-web-button
Checkbox.Item before-web-checkbox-item after-web-checkbox-item
List.Item before-web-list-item after-web-list-item
BottomNavigation before-web-bottom-navigation after-web-bottom-navigation
Chip before-web-chip-body after-web-chip-body
Chip close before-web-chip-close after-web-chip-close
FAB.Menu before-web-fab-menu after-web-fab-menu
Drawer.CollapsedItem before-web-drawer-collapsed-item after-web-drawer-collapsed-item
DataTable.Title before-web-data-table-title after-web-data-table-title
Appbar.Content before-web-appbar-content after-web-appbar-content

Android (emulator, hardware keyboard):

Before After
Button before-android-button after-android-button
Chip close before-android-chip-close after-android-chip-close
Drawer.CollapsedItem before-android-drawer-collapsed-item after-android-drawer-collapsed-item
FAB.Menu before-android-fab-menu after-android-fab-menu

On Android and iOS the ripple keeps its own height at the top of a chip
that style makes taller, so a ring drawn on it sat high. It also sat
inside the chip's 1dp border, so its gap to the visible edge was 1dp,
not 2dp. The ring now goes on the Surface, as on Card, and the ripple
only takes focus.
secondary has 2.04:1 contrast on the snackbar's inverseSurface in the
light theme and 1.32:1 in the dark one, below the 3:1 a focus indicator
needs. inversePrimary, the action label's color, has 7.73:1 and 4.97:1.
An internal context sets the ring color for those two controls only, so
there is no new prop and nothing else changes color.
Button, Card, the Chip body, FAB, FAB.Extended and the FAB.Menu trigger
and items draw their ring on a parent with a :has() rule, and hid the
browser outline on the focused element with an inline style. In a
browser without :has() (Chrome before 105, Safari before 15.4, Firefox
before 121) they showed no focus indicator at all.

The shared stylesheet now hides that outline, inside a supports block
that tests for :has(), so those browsers keep their own outline. It is
important, as the inline style was, so an app's own outline rules still
don't add a second indicator. The outline is drawn inside the edge, so
the FAB clip views don't cut it off.
@Doberjohn
Doberjohn merged commit 0181d96 into callstack:main Nov 16, 2026
10 checks passed
alpharius-ck added a commit that referenced this pull request Nov 16, 2026
Take main's shared keyboard focus ring (#5107):
- drop src/utils/focusRing.ts and take main's FAB, Switch and Checkbox
- drop IconButton's own focus state and ring view; the ring now comes from
  useFocusRing with 'within' on the clip view, so it surrounds the outline
  and the touchable no longer draws a second one
- keep the theme props on IconButton's TouchableRipple and TextInput.Icon
- regenerate snapshots, add IconButton focus ring wiring tests

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

No keyboard focus indicator on most components, and the three that have one each did it differently

6 participants