Keyboard handling and the Screen component

Screen in src/components/ui/Screen.tsx is the wrapper for every page. It owns the safe area, the background, scrolling, pull to refresh, a pinned footer and keyboard avoidance. Screens should not add their own KeyboardAvoidingView.

Structure

SafeAreaView                     edges, background
├── SkinBackground               when a home skin is active
├── AmbientGlow                  when no skin is active and glow is on
└── KeyboardAvoidingView         behavior="padding"
    ├── ScrollView or View       the body
    │   └── inner View           max width 480, horizontal padding
    └── footer View              optional, pinned under the body

Props

Prop	Default	Purpose
`children`		Page content
`scroll`	`false`	Wrap the body in a `ScrollView`
`padded`	`true`	Apply `spacing.screen` horizontal padding
`edges`	`['top']`	Safe area edges for the outer `SafeAreaView`
`footer`		Node pinned below the body. Turns on footer keyboard behaviour
`onRefresh`, `refreshing`		Adds a `RefreshControl` tinted with the brand color
`scrollEnabled`	`true`	Lets a child lock scrolling
`contentContainerStyle`		Merged into the inner view
`style`		Merged into the `SafeAreaView`
`onScroll`, `scrollEventThrottle`	throttle `16`	Passing `onScroll` switches to `Animated.ScrollView` so a Reanimated scroll handler works
`transparent`	`false`	No background. Used by home screens that draw their own
`glow`	`!transparent`	Render `AmbientGlow`
`scrollViewRef`		Receives the `ScrollView` instance
`onScrollViewLayout`		Layout callback for the scroll view
`scrollResetKey`		Used as the scroll view’s `key`. Change it to remount and jump to the top
`backgroundColor`		A fixed canvas color. Disables the skin backdrop and colors the footer to match

Behaviour that is always on:

keyboardShouldPersistTaps="handled", so a tap on a button works with the keyboard open.
Scroll content gets bottom padding of insets.bottom + spacing.huge + 72, which clears the tab bar and the global workout bar.
The inner view is centred and capped at sizes.maxContentWidth.

Background rules

Situation	Background
Default, classic skin	`colors.background` plus `AmbientGlow`
A skin is active (`glass`, `poster`, `bento`)	Transparent `SafeAreaView` over `SkinBackground`
`transparent`	Nothing. The screen composes its own
`backgroundColor` set	That color. No skin, no transparency

Keyboard avoidance

The rule in the code:

const liftFooter = Boolean(footer);
const avoidKeyboard = Platform.OS === 'android' || (Platform.OS === 'ios' && liftFooter);

Platform	Footer	`KeyboardAvoidingView`	ScrollView `automaticallyAdjustKeyboardInsets`	Reveal hook
iOS	No	Off	On	Off
iOS	Yes	On	Off	On, when `scroll` is true
Android	No	On	Not applicable, the prop is iOS only	Off
Android	Yes	On	Not applicable	Off

Android

The KeyboardAvoidingView is always enabled on Android. It pads the bottom by the keyboard height, the scroll view shrinks, and the native scroll view brings the focused input into view. The Android tab layout also sets tabBarHideOnKeyboard. Project notes record the reason this is done in JS: the Android build runs edge to edge, and under edge to edge the window no longer resizes for the keyboard on its own. The setting is edgeToEdgeEnabled=true in the generated android/gradle.properties. That folder is not tracked in Git. The scroll view’s native automaticallyAdjustKeyboardInsets handles everything. The KeyboardAvoidingView stays disabled so the two do not both add an inset. The footer has to ride above the keyboard, so the KeyboardAvoidingView is enabled with:

keyboardVerticalOffset={liftFooter ? -insets.bottom : 0}

The footer already pads itself by insets.bottom + spacing.md for the home indicator. With the keyboard open that safe-area padding is not needed, so the negative offset tucks it behind the keyboard and the buttons sit spacing.md above it. automaticallyAdjustKeyboardInsets is turned off here. The native handler lines the input up with the top of the keyboard, which is now covered by the footer. useRevealFocusedInput replaces it.

useRevealFocusedInput

src/lib/useRevealFocusedInput.ts is enabled only for iOS screens that have both footer and scroll. It returns setScrollRef, contentRef, footerRef and onScrollLayout, which Screen attaches to the scroll view, the inner view and the footer. reveal() runs on keyboardDidShow and whenever the scroll view’s layout height shrinks:

Take the focused input from TextInput.State.currentlyFocusedInput().
Measure its position inside the inner content view with measureLayout. This fails quietly for an input that is not inside this screen.
Measure the footer’s top and the input’s top in window coordinates.
If the input’s bottom is above the footer, do nothing.
Otherwise scroll to inputY + inputHeight - viewportHeight, which puts the input’s bottom at the bottom of the visible area.

Footers

Pass primary actions through footer instead of positioning them absolutely:

<Screen scroll footer={<Button label={strings.save} onPress={save} fullWidth />}>
  {fields}
</Screen>

The footer has a hairline top border, the page background, and the same max width as the body. Form screens use this for their step buttons. See Forms rendering.

Scroll locking

A child that handles horizontal or vertical drags inside a scrolling screen must stop the page from scrolling while the finger is down. The pattern is to hold a flag in the screen and pass scrollEnabled={!dragging}. The form range slider does this. Without it the scroll view steals the gesture.

Modals and sheets

Screen only manages its own tree. A Modal is a separate native window, so a sheet with an input needs its own KeyboardAvoidingView as its root. The barcode sheet in the nutrition feature does this.

Other keyboard details

Tapping outside an input does not dismiss the keyboard by default. Screens that need it call Keyboard.dismiss() from a backdrop press.
TextField with multiline grows with its content up to maxLines, so a long answer pushes the layout and the reveal logic keeps the caret line visible.
OtpInput auto-focuses on mount.

​Structure

​Props

​Background rules

​Keyboard avoidance

​Android

​iOS without a footer

​iOS with a footer

​useRevealFocusedInput

​Footers

​Scroll locking

​Modals and sheets

​Other keyboard details