Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
51 commits
Select commit Hold shift + click to select a range
3a7cccd
feat: add MD3 keyboard focus indicators
lukemorawski Aug 28, 2026
34a207a
fix: drive the focus ring with :focus-visible on web, not JS state
k0ndee Sep 7, 2026
b5b4e1a
chore: update snapshots after rebasing onto main
k0ndee Sep 7, 2026
7332cec
test: correct snapshots after combining focus-ring and hitSlop rebase
k0ndee Sep 9, 2026
a4c31b4
test: fix snapshots after rebase
k0ndee Sep 23, 2026
e2d40c3
test: fix imports and snapshots after rebasing onto #5108
Stoneski93 Nov 6, 2026
2256d79
fix(switch): show the focus ring on the track on web
Stoneski93 Nov 10, 2026
4a7ed7d
fix(bottom-navigation): draw the tab focus ring inward
Stoneski93 Nov 10, 2026
7266263
fix(chip): draw the body focus ring outward
Stoneski93 Nov 13, 2026
900a103
fix(chip): ring the close button with a circle around the glyph
Stoneski93 Nov 13, 2026
9907619
fix(checkbox): draw the Checkbox.Item focus ring inward
Stoneski93 Nov 13, 2026
125bd2e
fix(list): draw the List.Accordion focus ring inward
Stoneski93 Nov 13, 2026
cc291ba
fix(menu): draw the Menu.Item focus ring inward
Stoneski93 Nov 13, 2026
3f3c43b
fix(fab): draw the FAB.Menu item focus ring inward
Stoneski93 Nov 13, 2026
a22daf1
test(button): pin the outward focus ring and drop a stale TODO
Stoneski93 Nov 13, 2026
df007cb
fix(chip): size the close ring like Material Web, clear of the label
Stoneski93 Nov 13, 2026
bfca5db
fix(data-table): draw the DataTable.Row focus ring inward
Stoneski93 Nov 13, 2026
8c154cd
feat(data-table): add the focus ring to sortable DataTable.Title
Stoneski93 Nov 13, 2026
a6746e3
feat(drawer): add the focus ring to Drawer.CollapsedItem
Stoneski93 Nov 13, 2026
fa7e210
feat(appbar): add the focus ring to pressable Appbar.Content
Stoneski93 Nov 13, 2026
bd4f112
docs(segmented-buttons): explain the inward focus ring and pin it
Stoneski93 Nov 13, 2026
4f0d8fe
fix: keep a caller's own dataSet alongside the focus ring attribute
Stoneski93 Nov 13, 2026
ff41738
fix(data-table): draw the DataTable.Cell focus ring inward
Stoneski93 Nov 13, 2026
bc8698c
fix(drawer): draw the Drawer.CollapsedItem ring above the indicator
Stoneski93 Nov 13, 2026
8fcf978
fix(chip): keep the close ring round on Android
Stoneski93 Nov 13, 2026
ae301c9
fix: drop Android's grey focus highlight under the focus ring
Stoneski93 Nov 13, 2026
cc24440
fix(chip): keep the close button inside the chip on Android
Stoneski93 Nov 13, 2026
8a9c276
Merge remote-tracking branch 'origin/main' into @k0ndee/focus-indicators
Doberjohn Nov 15, 2026
751a01a
docs(migration): describe the keyboard focus indicator
Doberjohn Nov 15, 2026
8b48201
fix: don't ring a container when focus moves inside it
Doberjohn Nov 15, 2026
42c3f36
fix: clear a stale focus ring on Card and the Chip close button
Doberjohn Nov 15, 2026
4b5aa14
fix: draw the focus ring in a component's theme prop color
Doberjohn Nov 15, 2026
13ed02e
fix: let a caller's focusRing and android_ripple override the defaults
Doberjohn Nov 15, 2026
59f1e2e
fix(drawer): draw Drawer.Item's focus ring inside the item
Doberjohn Nov 15, 2026
e7e6f51
docs(touchable-ripple): clarify when the focusRing ring shows
Doberjohn Nov 15, 2026
4dab826
fix: keep the focus ring working when a test fires focus with no event
Doberjohn Nov 15, 2026
ad70168
fix: keep the inward ring visible over a row's own background
Doberjohn Nov 15, 2026
dde9e4c
fix(button): keep the focus ring 2dp outside an outlined button
Doberjohn Nov 15, 2026
04a0a3e
fix(drawer): keep the collapsed item's ring clear of its indicator
Doberjohn Nov 15, 2026
76e4ce0
fix(card): ring and press the whole card when it outgrows its content
Doberjohn Nov 15, 2026
92583a9
fix(appbar): draw Appbar.Action's focus ring in its theme color
Doberjohn Nov 15, 2026
0292799
fix(card): ring the card's edge instead of growing its press area
Doberjohn Nov 15, 2026
e49751e
fix(drawer): keep the collapsed item's ring clear of a long label
Doberjohn Nov 15, 2026
ff412c2
fix: don't ring a card on web when a control inside it has focus
Doberjohn Nov 15, 2026
3a2b3b6
fix(appbar): pass a medium or large Appbar's theme to its contents
Doberjohn Nov 15, 2026
28504ea
test: check the web focus ring structure with the web TouchableRipple
Doberjohn Nov 15, 2026
d877c8f
test(appbar): cover a leading action in the themed Appbar test
Doberjohn Nov 15, 2026
5ff6547
docs(migration): scope the medium and large Appbar theme note
Doberjohn Nov 15, 2026
c1848af
fix(chip): draw the body focus ring on the chip's own box
Doberjohn Nov 15, 2026
83c8211
fix(snackbar): ring the action and close button in inversePrimary
Doberjohn Nov 16, 2026
352fa2f
fix: keep the browser focus outline where :has() is unsupported
Doberjohn Nov 16, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 32 additions & 0 deletions docs/6.x/docs/guides/migration.md
Original file line number Diff line number Diff line change
Expand Up @@ -360,6 +360,34 @@ App tests change with it: a display-only element is no longer found by a role it

In a disabled `TextInput`, every `TextInput.Icon` takes the disabled color, also over `iconColor` and the error color. One with a handler is a disabled `IconButton`, and an `opacity` in its `style` doesn't apply.

### Focus indicator

Interactive components now draw the Material Design 3 keyboard focus indicator: a 3dp ring in `theme.colors.secondary`, 2dp outside the component. On web it shows when an element gets focus from the keyboard (`:focus-visible`), and on Android when it gets focus from a hardware keyboard or D-pad. Clicking or touching an element shows no ring. iOS shows no ring.

`Snackbar` rings its action and close button in `theme.colors.inversePrimary`, the color of its action label, because `secondary` barely shows on its `inverseSurface` background. If a component's background is the ring color, such as an `Appbar` with a `secondary` background, the rings of the controls on it don't show: give those controls a `theme` with a contrasting `secondary`. An `Appbar` passes its own `theme` on to the `Appbar.Action`, `Appbar.BackAction` and `Appbar.Content` placed directly in it.

Components that fill a clipping container or touch their neighbours draw the ring 3dp inside their edge instead: `List.Item`, `List.Accordion`, `Checkbox.Item`, `RadioButton.Item`, `Menu.Item`, the `FAB.Menu` items, `Drawer.Item`, the `BottomNavigation` tabs, `DataTable.Row`, `DataTable.Cell`, `DataTable.Title` and `SegmentedButtons`. `Drawer.CollapsedItem` draws it around its icon and label, 2dp clear of the active indicator. `FAB` and `Switch` draw this ring instead of their own, and `Checkbox` keeps its circular ring around the state layer.

A `TouchableRipple`, and every component built on it, rings only while it can be pressed. A disabled one shows no ring. One with no touch handler and no `disabled` is the plain view described in [TouchableRipple without a press handler](#touchableripple-without-a-press-handler): it isn't a keyboard stop, so it never rings. This applies to `TouchableRipple` only: a `Switch` or `Drawer.CollapsedItem` without a handler is still a keyboard stop and rings.

An outward ring sits outside the component, so a scroll view or a container with `overflow: 'hidden'` clips it, and a neighbour that touches the component can cover it. Chips in a horizontal `ScrollView`, or a `TouchableRipple` that fills the width of a scroll view, show only part of the ring. Give the container 5dp of padding, or pass `focusRing="inward"` where the component takes it:

```tsx
<ScrollView horizontal contentContainerStyle={{ padding: 5 }}>
<Chip onPress={showMusic}>Music</Chip>
</ScrollView>

<TouchableRipple focusRing="inward" onPress={openSettings}>
<Text>Settings</Text>
</TouchableRipple>
```

`TouchableRipple` takes a new `focusRing` prop, and so do the components whose props include it, such as `IconButton`, `List.Item`, `DataTable.Row` and `DataTable.Cell`. It is `'outward'`, `'inward'` or `'none'`. `'none'` draws no ring, but on web it leaves the browser's own focus outline, so a component that draws its own indicator also needs `outline: 'none'` on web.

On web the ring comes from a stylesheet that Paper adds to the page, and on these elements it takes precedence over your own `:focus-visible` outline styles. There is no app-wide switch to turn the ring off. Its color follows `theme.colors.secondary`, from the theme or a component's `theme` prop.

On web, `Button`, `Card`, the `Chip` body, `FAB`, `FAB.Extended` and the `FAB.Menu` trigger and items draw the ring with the CSS `:has()` selector. A browser without it (Chrome before 105, Safari before 15.4, Firefox before 121) shows its own focus outline just inside their edge instead.

### Libraries built on Paper

Libraries built on Paper may not support 6.x yet. For example, `react-native-paper-dates` 0.24.1 still uses `HelperText`, the 5.x theme exports and `theme.roundness`, so its `DatePickerInput` crashes when it shows a validation error.
Expand Down Expand Up @@ -405,6 +433,8 @@ To keep the height of the content row when setting `height` in `style`, add the
</Appbar.Header>
```

In `medium` and `large` mode, `Appbar` now passes its `theme` to `Appbar.BackAction`, `Appbar.Action` and `Appbar.Content`, as the `small` and `center-aligned` modes already did. These children of a medium or large bar with its own `theme` now take their colors, the title's font and their focus rings from that theme, not from the app's. In 5.x, a dark-themed bar in a light app drew dark icons and a dark title on its dark background.

### Avatar

The `style` prop for `Avatar.Icon`, `Avatar.Image` and `Avatar.Text` no longer configures the background color. Use the `backgroundColor` prop instead. The text or icon color is still derived from the background color unless `color` is specified.
Expand Down Expand Up @@ -673,6 +703,8 @@ Corner radii set through `style` no longer shape the press, hover and disabled f

`hitSlop` now works on web: the touchable renders an invisible target that extends past its bounds. An ancestor with `overflow: 'hidden'` or a scroll view clips it, as on Android.

`TouchableRipple` draws the keyboard focus ring and takes a new `focusRing` prop. See [Focus indicator](#focus-indicator).

### TextInput

The Paper 6.x `TextInput` is a complete rewrite with a new API. Import the component the same way, but note that the props and behavior have changed significantly.
Expand Down
4 changes: 4 additions & 0 deletions src/components/Appbar/Appbar.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -258,12 +258,14 @@ const Appbar = ({
{renderAppbarContent({
children,
isDark,
theme,
renderOnly: ['Appbar.BackAction'],
mode,
})}
{renderAppbarContent({
children: filterAppbarActions(children, true),
isDark,
theme,
renderOnly: ['Appbar.Action'],
mode,
})}
Expand All @@ -272,6 +274,7 @@ const Appbar = ({
{renderAppbarContent({
children: filterAppbarActions(children),
isDark,
theme,
renderExcept: [
'Appbar',
'Appbar.BackAction',
Expand All @@ -285,6 +288,7 @@ const Appbar = ({
{renderAppbarContent({
children,
isDark,
theme,
renderOnly: ['Appbar.Content'],
mode,
})}
Expand Down
1 change: 1 addition & 0 deletions src/components/Appbar/AppbarAction.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -100,6 +100,7 @@ const AppbarAction = ({
disabled={disabled}
aria-label={ariaLabel}
animated
theme={theme}
ref={ref}
{...rest}
/>
Expand Down
22 changes: 22 additions & 0 deletions src/components/Appbar/AppbarContent.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ import type {
import { modeTextVariant } from './utils';
import { useInternalTheme } from '../../core/theming';
import type { ThemeProp } from '../../theme/types';
import { mergeDataSetProps, useFocusRing } from '../../utils/useFocusRing';
import Text from '../Typography/Text';
import type { TextRef } from '../Typography/Text';

Expand Down Expand Up @@ -101,6 +102,14 @@ const AppbarContent = ({
const theme = useInternalTheme(themeOverrides);
const { colors, fonts } = theme;

// With `onPress` the title is a button, so it gets the keyboard focus ring
// (MD3: interactive elements in an app bar have focus rings). It is a plain
// `Pressable`, so it calls the hook directly. Outward, the default.
const { target: focusTarget, ring: focusRing } = useFocusRing(
disabled || !onPress,
colors.secondary
);

const titleTextColor = titleColor ? titleColor : colors.onSurface;

const modeContainerStyles = {
Expand Down Expand Up @@ -153,6 +162,19 @@ const AppbarContent = ({
onPress={onPress}
disabled={disabled}
{...contentWrapperProps}
// Like Switch: a ripple drawable owns the focused state, so Android does
// not add its grey default focus highlight on top of the ring.
android_ripple={{ color: 'transparent' }}
onFocus={(e) => {
focusTarget.onFocus?.(e);
rest.onFocus?.(e);
}}
onBlur={(e) => {
focusTarget.onBlur?.();
rest.onBlur?.(e);
}}
{...mergeDataSetProps(rest, focusRing.dataSetProps)}
style={[...contentWrapperProps.style, ...focusRing.style]}
>
{content}
</Pressable>
Expand Down
9 changes: 9 additions & 0 deletions src/components/BottomNavigation/BottomNavigationBar.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -213,6 +213,8 @@ const Touchable = <Route extends BaseRoute>({
borderless,
centered,
rippleColor,
focusRing,
theme,
...rest
}: TouchableProps<Route>) =>
TouchableRipple.supported ? (
Expand All @@ -222,6 +224,8 @@ const Touchable = <Route extends BaseRoute>({
borderless={borderless}
centered={centered}
rippleColor={rippleColor}
focusRing={focusRing}
theme={theme}
style={style}
>
{children}
Expand Down Expand Up @@ -574,6 +578,11 @@ const BottomNavigationBar = <Route extends BaseRoute>({
borderless: true,
centered: true,
rippleColor: 'transparent',
// Tabs fill the bar edge to edge and the bar clips
// (`overflow: 'hidden'`), so an outward ring would lose its top
// and bottom and read as two vertical lines between tabs.
focusRing: 'inward',
theme,
onPress: () => onTabPress(eventForIndex(index)),
onLongPress: () => onTabLongPress?.(eventForIndex(index)),
testID: getTestID({ route }),
Expand Down
31 changes: 21 additions & 10 deletions src/components/Button/Button.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ import { useReduceMotion } from '../../theme/accessibility/ReduceMotionContext';
import { toSpringCurve } from '../../theme/tokens/sys/motion';
import type { ThemeProp } from '../../theme/types';
import hasTouchHandler from '../../utils/hasTouchHandler';
import { useFocusRing } from '../../utils/useFocusRing';
import ActivityIndicator from '../ActivityIndicator';
import Icon from '../Icon';
import type { IconSource } from '../Icon';
Expand Down Expand Up @@ -446,14 +447,18 @@ const Button = ({
// The clip carries the same radius transition as the `Surface`, so the
// ripple and the disabled overlay follow the morph.
//
// TODO: revisit the focus ring's placement once #5084 lands.
// https://github.com/callstack/react-native-paper/pull/5084 adds MD3 keyboard
// focus indicators to every `TouchableRipple` consumer, so Button gets one
// with no code here. Deliberately not implemented locally: a second ring here
// would double up with it. The catch is placement — that PR defaults to
// `focusRing="outward"` and warns an outward ring is trimmed by "any clipping
// ancestor sized to its content", which is exactly this view. Button will
// likely need `focusRing="inward"`, or the ring on the outer view.
// The keyboard focus ring goes on the clip (`scope: 'within'`, as on FAB),
// not on the ripple that takes focus: the ripple sits inside the outline's
// border, so a ring measured from it would lose the border width from its
// 2dp gap, and overlap a thick outline. Neither this view nor the `Surface`
// sets `overflow`, so nothing here trims it. Off whenever the button can't
// be pressed, as on TouchableRipple.
const { target: focusTarget, ring: focusRing } = useFocusRing(
disabled || !hasPassedTouchHandler,
theme.colors.secondary,
'outward',
'within'
);
const shapeTransitionStyle = {
transitionProperty: 'borderRadius',
transitionDuration: shapeTransitionDuration,
Expand Down Expand Up @@ -496,7 +501,10 @@ const Button = ({
shapeTransitionTimingFunction={shapeTimingFunction}
style={[styles.button, style]}
>
<Reanimated.View style={[styles.clip, outlineStyle, clipStyle]}>
<Reanimated.View
style={[styles.clip, outlineStyle, clipStyle, ...focusRing.style]}
{...focusRing.dataSetProps}
>
{backgroundOpacity < 1 && (
<Reanimated.View
pointerEvents="none"
Expand All @@ -509,7 +517,10 @@ const Button = ({
)}
<AnimatedTouchableRipple
borderless
style={innerClipStyle}
focusRing="none"
onFocus={focusTarget.onFocus}
onBlur={focusTarget.onBlur}
style={[innerClipStyle, ...focusTarget.style]}
background={background}
rippleColor={rippleColor}
onPress={onPress}
Expand Down
25 changes: 23 additions & 2 deletions src/components/Card/Card.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ import { getCardColors } from './utils';
import { useInternalTheme } from '../../core/theming';
import type { Elevation, ThemeProp } from '../../theme/types';
import hasTouchHandler from '../../utils/hasTouchHandler';
import { mergeDataSetProps, useFocusRing } from '../../utils/useFocusRing';
import Surface from '../Surface';
import type { SurfaceStyle } from '../Surface';

Expand Down Expand Up @@ -165,7 +166,6 @@ const Card = ({
...rest
}: (OutlinedCardProps | ElevatedCardProps | ContainedCardProps) & Props) => {
const theme = useInternalTheme(themeOverrides);

const isMode = React.useCallback(
(modeToCompare: Mode) => {
return cardMode === modeToCompare;
Expand All @@ -180,6 +180,20 @@ const Card = ({
onPressOut,
});

// The ring goes on the Surface, the card's visible box (`scope: 'within'`),
// not on the `Pressable` that takes focus: the caller's `style` sizes and
// pads the Surface, so a ring on the content-sized `Pressable` would stop
// short of a taller card's edge or sit inside its padding.
//
// Off without a touch handler too: the `Pressable` unmounts then, and a
// focused one sends no blur, so the ring would come back with the handler.
const { target: focusTarget, ring: focusRing } = useFocusRing(
disabled || !hasPassedTouchHandler,
theme.colors.secondary,
'outward',
'within'
);

const [pressed, setPressed] = React.useState(false);
const elevation = isMode('elevated') ? (pressed ? 2 : cardElevation) : 0;

Expand Down Expand Up @@ -237,11 +251,12 @@ const Card = ({
ref={ref}
borderRadius={borderRadius}
backgroundColor={!isMode('elevated') ? backgroundColor : undefined}
style={style}
style={[style, ...focusRing.style]}
theme={theme}
elevation={elevation}
testID={hasPassedTouchHandler ? undefined : testID}
{...rest}
{...mergeDataSetProps(rest, focusRing.dataSetProps)}
>
{isMode('outlined') && (
<View
Expand All @@ -267,6 +282,12 @@ const Card = ({
onPressIn={handlePressIn}
onPressOut={handlePressOut}
testID={testID}
// Like Switch: a ripple drawable owns the focused state, so Android does
// not add its grey default focus highlight on top of the ring.
android_ripple={{ color: 'transparent' }}
onFocus={focusTarget.onFocus}
onBlur={focusTarget.onBlur}
style={[{ borderRadius }, ...focusTarget.style]}
>
{content}
</Pressable>
Expand Down
2 changes: 2 additions & 0 deletions src/components/Checkbox/Checkbox.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -499,6 +499,8 @@ const Checkbox = ({
onBlur={handleBlur}
{...interactionHandlers}
borderless
// Checkbox draws its own circular ring around the state layer.
focusRing="none"
// The platform press paints the wrong thing: it covers the whole 48dp
// target instead of the 40dp state layer, tints with a neutral role,
// and on web its hover overlay doubles up with the layer. Android also
Expand Down
28 changes: 27 additions & 1 deletion src/components/Checkbox/CheckboxItem.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,8 @@ import Checkbox from './Checkbox';
import { useInternalTheme } from '../../core/theming';
import type { ThemeProp, TypescaleKey } from '../../theme/types';
import { getStateLayer } from '../../theme/utils/state';
import hasTouchHandler from '../../utils/hasTouchHandler';
import { useFocusRing } from '../../utils/useFocusRing';
import { useSpaceKeyPress } from '../../utils/useSpaceKeyPress';
import TouchableRipple from '../TouchableRipple/TouchableRipple';
import type { Props as TouchableRippleProps } from '../TouchableRipple/TouchableRipple';
Expand Down Expand Up @@ -160,16 +162,35 @@ const CheckboxItem = ({
textAlign,
};

// A full-width row: an outward ring would run into the rows around it. Inward,
// the ring goes on a childless overlay painted last (`'descendant'`): drawn
// on the row itself, it would sit under the content view, and a background
// set through `style` would hide it. Off
// whenever the row can't be pressed, as on TouchableRipple.
const { target: focusTarget, ring: focusRing } = useFocusRing(
disabled || !hasTouchHandler({ onPress, onLongPress }),
theme.colors.secondary,
'inward',
'descendant'
);

return (
<TouchableRipple
aria-label={ariaLabel}
focusRing="none"
role="checkbox"
aria-checked={status === 'indeterminate' ? 'mixed' : status === 'checked'}
aria-disabled={disabled}
onPress={onPress}
onLongPress={onLongPress}
onBlur={handleSpaceKeyBlur}
onFocus={focusTarget.onFocus}
onBlur={(e) => {
handleSpaceKeyBlur(e);
focusTarget.onBlur?.();
}}
{...spaceKeyHandlers}
{...focusTarget.dataSetProps}
style={focusTarget.style}
testID={testID}
disabled={disabled}
theme={theme}
Expand All @@ -191,6 +212,11 @@ const CheckboxItem = ({
</Text>
{!isLeading && checkbox}
</View>
<View
pointerEvents="none"
style={[StyleSheet.absoluteFill, ...focusRing.style]}
{...focusRing.dataSetProps}
/>
</TouchableRipple>
);
};
Expand Down
Loading
Loading