docs: replace FAB and Switch screenshots with live interactive examples by hristototov · Pull Request #5069 · callstack/react-native-paper

hristototov · 2026-08-24T12:01:19Z

Motivation

Parts of the documentation have drifted out of sync with the v6 modernisation effort. The FAB and Switch pages were still illustrated with screenshots captured before those components were reworked for the latest Material Design 3 spec, so they showed outdated naming and token references:

FAB had an "all modes" screenshot tab, but the component no longer has a mode prop — it's variant (six role-color presets) and size (three spec sizes) now.
Switch was documented with a four-way Android (enabled/disabled) / iOS (enabled/disabled) screenshot split, which no longer reflects reality: the modernised component renders the same MD3 visuals on both platforms.

Static images also can't show what these components actually do - the Switch handle animation, the Extended FAB expand/collapse transition - and they silently rot every time a component changes.

This PR drops those screenshots and inlines the real components instead, so the docs render live from

Related issue

Closes #4991

Implementation notes

A general mechanism rather than a one-off, so the remaining outdated pages can follow:

docs/src/data/liveExamples.ts - new registry mapping a component title to the example module and named exports to render. Adding an entry here automatically removes that component's screenshot tabs, so a component is documented either with screenshots or with live examples, never both. The invariant is enforced in one place in generatePageMDX.ts.
docs/src/components/InteractiveExample.tsx - shared shell for embedded demos. Paper components reach browser APIs through react-native-web, so the tree mounts client-only behind BrowserOnly with a same-sized placeholder during SSR to avoid layout shift, and the Paper theme is kept in sync with the active docs color mode. Follows the existing pattern in BannerExample.tsx.
FABExample.tsx / SwitchExample.tsx - the actual demos. The FAB variant and size lists mirror the Variant and Size unions in src/components/FAB/tokens.ts in order, so a spec change surfaces as a type error rather than a stale image.

Also includes one small runtime fix surfaced while building the demos: Switch's absoluteFill style was missing alignItems / justifyContent, so the unselected icon which is smaller than the SELECTED_ICON-sized iconWrap it sits in - was pinned to the top-left instead of centered. Snapshots updated accordingly.

Images

…into hristototov/revisit-docs

JKobrynski

LGTM!

satya164

Please avoid emdashes and claudism in text. Using LLM is fine but we shouldn't make our documentation look AI generated without human attention.

satya164 · 2026-08-25T16:26:52Z

+  'tonalPrimary',
+  'tonalSecondary',
+  'tonalTertiary',
+] as const;


Remove the comment. Annotate the VARIANTS with a type based on the Variant so it actually stays in sync instead of the comment saying it does

satya164 · 2026-08-25T16:26:55Z

+/**
+ * Every spec size accepted by the `size` prop.
+ */
+const SIZES = ['default', 'medium', 'large'] as const;


Same as above

satya164 · 2026-08-25T16:29:52Z

+ * Paper components depend on browser APIs through `react-native-web`, so the
+ * tree is only mounted on the client and a same-sized placeholder is rendered
+ * during SSR to avoid layout shift. The Paper theme is kept in sync with the
+ * active docs color mode so demos match the surrounding page.


The comment is wrong for the component's content. There's nothing related to SSR here.

But also why are we only rendering these on client and skipping on SSR? We need to render components both on SSR and client.

updated

Dropped BrowserOnly and the Placeholder, then collapsed Frame + the pass-through InteractiveExample into a single component with no gate; the split had no purpose

Removed the now-dead .paper-interactive-example--loading class

Rewrote the comment

…into hristototov/revisit-docs

JKobrynski · 2026-09-09T11:56:33Z

+  const isDarkTheme = useColorMode().colorMode === 'dark';
+
+  return (
+    <Provider theme={isDarkTheme ? DarkTheme : LightTheme}>


Have you checked these in dark mode? I'm afraid they render with light-theme colors, so the caption under each switch ends up dark on dark and unreadable.

I have checked dark mode (even the screenshots are in dark mode) however, you're right about the text color - i didn't notice this. Fixed now 👍

Captions read fine now, thanks. The switches still come up light-themed on a first dark-mode load, though. They only turn dark after navigating away and back. Try a hard reload with a dark OS theme and nothing stored.

Good catch - the theme lookup was fine, but Paper bakes colors into inline styles and hydration keeps whatever the server painted, which is always light. Remounting the Provider on the client forces a repaint.

The recording below is the built output with a dark OS theme and empty storage:

dark-mode-walkthrough.webm

JKobrynski · 2026-09-09T11:57:07Z

+
+  return (
+    <InteractiveExample title="Extended">
+      <FAB.Extended


Have you checked the extended FAB on the built page?

Yes, checked it on the built output (yarn build + yarn preview), it renders correctly, and the interaction is as expected

…into hristototov/revisit-docs

Copilot

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

…into hristototov/revisit-docs

satya164 · 2026-10-22T19:05:29Z

Review by Claude

Web

The Switch captions and accessible labels go stale after a toggle.
- Steps: open the Switch page. In the "Enabled" example, click the switch captioned "selected", then the one captioned "unselected".
- What happens: the first switch is now off and the second is on, but the captions still read "selected" and "unselected". The aria-label values also stay "Selected" and "Unselected", so a screen reader announces "Selected, switch, off". The "With icons in the handle" example has the same problem.
- Expected: the caption matches the current state, and the label does not contradict aria-checked.
(via Claude, verify if it makes sense)
The FAB size captions sit at three different heights.
- Steps: open the FAB page and look at the "Sizes" example.
- What happens: the row centers each item vertically, so the "default", "medium" and "large" captions are on three different lines.
- Expected: the captions line up on one line.
(via Claude, verify if it makes sense)

satya164

Review by Claude

See the inline comments. (via Claude, verify if it makes sense)

satya164 · 2026-10-22T19:06:08Z

+        <Labelled label="selected">
+          <Switch value={on} onValueChange={setOn} aria-label="Selected" />
+        </Labelled>
+        <Labelled label="unselected">
+          <Switch value={off} onValueChange={setOff} aria-label="Unselected" />


The captions and aria-label values are fixed, but both switches toggle. After one click, the switch captioned "selected" is off, and a screen reader announces "Selected, switch, off".

Derive the caption from the value, and keep state words out of aria-label, because aria-checked already announces the state:

<Labelled label={first ? 'selected' : 'unselected'}> <Switch value={first} onValueChange={setFirst} aria-label="First switch" /> </Labelled>

The same applies to SwitchIconsExample. The disabled example can keep fixed captions, because those switches cannot change. (via Claude, verify if it makes sense)

satya164 · 2026-10-22T19:06:08Z

+  // The server always renders light colors, so remount to repaint in dark mode.
+  const [mounted, setMounted] = React.useState(false);
+
+  React.useEffect(() => {
+    setMounted(true);
+  }, []);
+
+  return (
+    <Provider
+      key={String(mounted)}
+      theme={isDarkTheme ? DarkTheme : LightTheme}
+    >


The key remount hides a hydration mismatch instead of avoiding it. Rspress reads matchMedia and the stored appearance in its initial client state, so useColorMode() already returns dark during hydration. The first client render then uses DarkTheme while the server HTML uses LightTheme. React keeps the server attributes in that case, and the key change throws away the hydrated tree and mounts every example a second time, also in light mode where nothing changed.

Use the light theme until after mount. Hydration then matches the server, and the switch to dark is a normal update:

Suggested change

// The server always renders light colors, so remount to repaint in dark mode.

const [mounted, setMounted] = React.useState(false);

React.useEffect(() => {

setMounted(true);

}, []);

return (

<Provider

key={String(mounted)}

theme={isDarkTheme ? DarkTheme : LightTheme}

>

// The server always renders light colors, so use them until hydration is done.

const [mounted, setMounted] = React.useState(false);

React.useEffect(() => {

setMounted(true);

}, []);

return (

<Provider theme={mounted && isDarkTheme ? DarkTheme : LightTheme}>

(via Claude, verify if it makes sense)

satya164 · 2026-10-22T19:06:08Z

+  row: {
+    flexDirection: 'row',
+    flexWrap: 'wrap',
+    alignItems: 'center',


With center, each item is centered on the tallest item in the row. In the Sizes example the three FABs have different heights, so the "default", "medium" and "large" captions sit on three different lines.

flex-end puts the captions on one line and does not change rows where all items have the same height:

Suggested change

alignItems: 'center',

alignItems: 'flex-end',

(via Claude, verify if it makes sense)

…into hristototov/revisit-docs

Hristo Totov added 2 commits August 24, 2026 14:57

docs: replace FAB and Switch screenshots with live interactive examples

150beac

Merge branch 'main' of https://github.com/callstack/react-native-paper …

0d28a4a

…into hristototov/revisit-docs

hristototov self-assigned this Aug 24, 2026

github-actions Bot added the Contributor: Internal label Aug 24, 2026

hristototov changed the title ~~Hristototov/revisit docs~~ docs: revisit documentation structure and organization Aug 24, 2026

hristototov changed the title ~~docs: revisit documentation structure and organization~~ docs: replace FAB and Switch screenshots with live interactive examples Aug 24, 2026

hristototov requested a review from satya164 August 24, 2026 12:02

JKobrynski approved these changes Aug 24, 2026

View reviewed changes

satya164 requested changes Aug 25, 2026

View reviewed changes

Hristo Totov added 2 commits August 26, 2026 11:07

Merge branch 'main' of https://github.com/callstack/react-native-paper …

946bcc9

…into hristototov/revisit-docs

fix: cr comments

2d2a8a3

hristototov requested a review from satya164 August 27, 2026 14:42

JKobrynski reviewed Aug 28, 2026

View reviewed changes

Comment thread docs/src/components/SwitchExample.tsx Outdated

fix: cr comments 2

99fc5ff

hristototov requested a review from JKobrynski August 28, 2026 13:21

Hristo Totov added 2 commits September 3, 2026 14:42

Merge branch 'main' of https://github.com/callstack/react-native-paper …

11022b3

…into hristototov/revisit-docs

fix(docs): restore live examples support in the reworked docs plugin

edfcb12

JKobrynski reviewed Sep 9, 2026

View reviewed changes

Hristo Totov added 3 commits September 10, 2026 11:36

Merge branch 'main' of https://github.com/callstack/react-native-paper …

081e3c0

…into hristototov/revisit-docs

fix: cr comments

f6b7086

Merge branch 'main' of https://github.com/callstack/react-native-paper …

79faefd

…into hristototov/revisit-docs

satya164 requested a balanced review from Copilot September 15, 2026 20:33

Copilot AI reviewed Sep 15, 2026

Hristo Totov added 2 commits September 29, 2026 11:17

Merge branch 'main' of https://github.com/callstack/react-native-paper …

e2339cc

…into hristototov/revisit-docs

fix(docs): repaint interactive examples after hydration in dark mode

dba0b4d

satya164 reviewed Oct 22, 2026

View reviewed changes

Hristo Totov added 2 commits October 24, 2026 11:24

Merge branch 'main' of https://github.com/callstack/react-native-paper …

2f46f9b

…into hristototov/revisit-docs

fix: cr comments

5dab461

hristototov requested a review from satya164 October 24, 2026 08:44

Conversation

hristototov commented Aug 24, 2026

Motivation

Related issue

Implementation notes

Images

Uh oh!

JKobrynski left a comment

Choose a reason for hiding this comment

Uh oh!

satya164 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

satya164 commented Oct 22, 2026

Web

Uh oh!

satya164 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants