react-native-screen-system

Behavior-first screen infrastructure for React Native.

Stop rewriting keyboard, focus, safe-area, and sticky-action logic on every screen. react-native-screen-system gives your team a set of small, composable primitives that wire together automatically — so you ship screens faster and keep them consistent.

Your keyboard will never hide a CTA button again.
Tab to the next field. Every time. No exceptions.
Safe area padding: set it once, forget it exists.
Loading · error · empty — three less if statements per screen.

Table of Contents

• Why Use It
• Install
• Setup
• Quick Example
• Architecture
• API Reference
  • ScreenSystemProvider
  • ScreenContainer
  • ScreenScrollView
  • StickyActionBar
  • ScreenStateView
  • useFocusableField
  • useFocusController
  • useScreenState
  • useKeyboardInsets
• Customization
• Examples
• Contributing
• License

Why Use It

Use this package when your app keeps running into problems like:

• inputs getting hidden behind the keyboard
• form fields needing reliable next and previous focus behavior
• bottom CTA bars needing to stay reachable on small devices
• long forms needing to scroll the focused input into view
• screen state handling repeating across loading, error, empty, and content flows
• safe-area padding being manually reimplemented on every screen

This package is not a design system or navigation framework. It focuses on the interaction layer underneath your UI:

• keyboard-aware screen layout
• safe-area-aware spacing
• focus order and input submit behavior
• scroll-to-focused-input behavior
• sticky bottom actions
• screen state orchestration

Good Fit Use Cases

• Sign in, sign up, OTP, forgot password, and recovery flows
• Checkout, shipping, billing, payment, and address entry screens
• Profile edit and account settings screens
• Onboarding and multi-step form flows
• Support and feedback forms
• Internal tools with many input-heavy screens
• Search, filter, and results screens with loading, empty, and error states

Install

npm install react-native-screen-system react-native-safe-area-context

Peer dependencies required:

| Package | Version | | --- | --- | | react | >=18.0.0 | | react-native | >=0.72.0 | | react-native-safe-area-context | >=4.0.0 |

Setup

Wrap your app once at the root. ScreenSystemProvider sets up shared context for all screens below it.

import { SafeAreaProvider } from 'react-native-safe-area-context';
import { ScreenSystemProvider } from 'react-native-screen-system';

export function App() {
  return (
    <SafeAreaProvider>
      <ScreenSystemProvider>
        <RootApp />
      </ScreenSystemProvider>
    </SafeAreaProvider>
  );
}

Quick Example

A complete login screen — keyboard-aware layout, focus order, and sticky CTA — in under 40 lines:

import { Button, TextInput } from 'react-native';
import {
  ScreenContainer,
  ScreenScrollView,
  StickyActionBar,
  useFocusableField,
} from 'react-native-screen-system';

export function LoginScreen() {
  const email = useFocusableField({ id: 'email', order: 1, submitBehavior: 'next' });
  const password = useFocusableField({ id: 'password', order: 2, submitBehavior: 'blur' });

  return (
    <ScreenContainer keyboardAware includeBottomInset>
      <ScreenScrollView contentContainerStyle={{ padding: 16 }}>
        <TextInput
          ref={email.ref}
          placeholder="Email"
          onFocus={email.onFocus}
          onSubmitEditing={email.onSubmitEditing}
        />
        <TextInput
          ref={password.ref}
          placeholder="Password"
          secureTextEntry
          onFocus={password.onFocus}
          onSubmitEditing={password.onSubmitEditing}
        />
      </ScreenScrollView>

      <StickyActionBar divider>
        <Button title="Continue" onPress={() => {}} />
      </StickyActionBar>
    </ScreenContainer>
  );
}

Architecture

ScreenSystemProvider sets up three contexts internally — FocusControllerProvider, ScrollCoordinatorProvider, and ScreenSystemContext — so every component and hook shares the same state without any manual wiring.

useKeyboardInsets works standalone and does not require the provider.

API Reference

ScreenSystemProvider

App-level defaults. Override these once instead of repeating per screen.

| Prop | Type | Default | Description | | --- | --- | --- | --- | | keyboardVerticalOffset | number | 0 | Base offset subtracted from keyboard spacing across the app | | actionBarBottomGap | number | 12 | Default extra bottom gap for sticky action bars | | defaultKeyboardBehavior | 'padding' \| 'margin' \| 'none' | 'padding' | Default keyboard behavior for ScreenContainer | | defaultActionBarKeyboardBehavior | 'padding' \| 'margin' \| 'none' | 'padding' | Default keyboard behavior for StickyActionBar |

ScreenContainer

Screen wrapper with keyboard and inset-aware spacing. Renders a View with flex: 1.

| Prop | Type | Default | Description | | --- | --- | --- | --- | | keyboardAware | boolean | false | Turns on keyboard-aware bottom spacing | | keyboardBehavior | 'padding' \| 'margin' \| 'none' | 'padding' | Controls how keyboard space is applied | | keyboardVerticalOffset | number | — | Per-screen keyboard offset override | | keyboardInsetOverride | number | — | Manual keyboard inset override | | keyboardInsetAdjustment | number | 0 | Fine-tunes the computed keyboard inset | | includeTopInset | boolean | false | Adds safe area top inset | | includeBottomInset | boolean | true | Adds safe area bottom inset | | topInsetOverride | number | — | Manual top inset override | | bottomInsetOverride | number | — | Manual bottom inset override | | extraTopInset | number | 0 | Adds extra top spacing on top of inset | | extraBottomInset | number | 0 | Adds extra bottom spacing on top of inset |

Accepts all ViewProps.

ScreenScrollView

A ScrollView wrapper that registers with the scroll coordinator so focused inputs are scrolled into view automatically.

| Prop | Type | Default | Description | | --- | --- | --- | --- | | scrollSystemId | string | 'default-scroll-view' | Unique id for the registered scroll view | | autoRegister | boolean | true | Automatically registers with the scroll coordinator | | enabled | boolean | true | Enables or disables scroll-to-field for this view | | scrollToFocusedInputOffset | number | 24 | Extra space left above the focused input | | preventNegativeScrollOffset | boolean | true | Prevents scroll overshoot above the top | | fallbackTopInset | number | 0 | Extra top inset for the manual scroll fallback |

Accepts all ScrollViewProps. Supports forwardRef.

StickyActionBar

Bottom action area that stays visible above the keyboard and respects safe area.

| Prop | Type | Default | Description | | --- | --- | --- | --- | | keyboardAware | boolean | true | Moves the action bar above the keyboard | | keyboardBehavior | 'padding' \| 'margin' \| 'none' | 'padding' | Controls how keyboard space is applied | | safeAreaAware | boolean | true | Includes bottom safe area spacing | | keyboardVerticalOffset | number | — | Per-bar keyboard offset override | | keyboardInsetOverride | number | — | Manual keyboard inset override | | safeAreaInsetOverride | number | — | Manual bottom safe area override | | bottomOffset | number | 12 | Extra bottom gap under the action bar content | | divider | boolean | false | Shows a hairline divider above the action bar | | dividerColor | string | '#D1D5DB' | Custom divider color |

Accepts all ViewProps.

ScreenStateView

Renders different content based on screen state. Accepts either an explicit state prop or individual boolean flags.

| Prop | Type | Default | Description | | --- | --- | --- | --- | | state | ScreenStatus | — | Explicit state override ('loading' \| 'error' \| 'empty' \| 'content') | | loading | boolean | false | Loading flag (ignored when state is set) | | error | unknown \| null | null | Error value (ignored when state is set) | | empty | boolean | false | Empty flag (ignored when state is set) | | renderLoading | () => ReactNode | — | Custom loading renderer | | renderError | (error) => ReactNode | — | Custom error renderer | | renderEmpty | () => ReactNode | — | Custom empty renderer | | renderContent | () => ReactNode | — | Custom content renderer (falls back to children) | | children | ReactNode | — | Default content, used when no renderContent is provided |

useFocusableField

Wires a TextInput into the focus system. Returns a ref, event handlers, and imperative focus helpers.

Options:

| Option | Type | Default | Description | | --- | --- | --- | --- | | id | string | — | Required. Stable field id used by the focus system | | order | number | — | Required. Order used for next / previous navigation | | nextId | string | — | Explicit next field id | | previousId | string | — | Explicit previous field id | | targetId | string | — | Explicit submit target field id | | disabled | boolean | false | Excludes the field from navigation when true | | submitBehavior | 'next' \| 'previous' \| 'target' \| 'blur' \| 'none' | auto-detected | What happens when the user submits the field | | blurOnSubmit | boolean | false | Blur the field on submit (used in auto-detection fallback) | | autoScrollOnFocus | boolean | true | Scrolls the field into view when it receives focus | | scrollToFocusedInputOffset | number | — | Extra space above the focused field during scroll | | preventNegativeScrollOffset | boolean | — | Prevents scroll overshoot above the top | | onFocus | () => void | — | Called when the field receives focus | | onSubmitEditing | (event) => void | — | Called when the field's submit button is tapped |

submitBehavior auto-detection (when not explicitly set):

• Has targetId or nextId → 'target'
• Has previousId → 'previous'
• blurOnSubmit is true → 'blur'
• Otherwise → 'next'

Returns:

| Field | Type | Description | | --- | --- | --- | | ref | RefObject<TextInput \| null> | Attach to the TextInput | | onFocus | () => void | Attach to TextInput.onFocus | | onSubmitEditing | (event) => void | Attach to TextInput.onSubmitEditing | | focusNext | () => boolean | Imperatively focuses the next field | | focusPrevious | () => boolean | Imperatively focuses the previous field | | focusSelf | () => boolean | Imperatively focuses this field |

useFocusController

Imperative focus controller. Useful for form validation (focus first invalid field) and custom UI interactions.

| Field | Type | Description | | --- | --- | --- | | registerField | (field) => () => void | Registers a field manually; returns an unregister function | | focusField | (id) => boolean | Focuses a field by id | | focusNext | (currentId) => boolean | Focuses the next registered field after currentId | | focusPrevious | (currentId) => boolean | Focuses the previous registered field before currentId | | focusFirstInvalid | (invalidIds) => boolean | Focuses the first focusable field in invalidIds |

Must be used inside ScreenSystemProvider.

useScreenState

Converts boolean flags into a single ScreenStatus string. Priority: loading → error → empty → content.

Options:

| Option | Type | Default | Description | | --- | --- | --- | --- | | loading | boolean | false | Signals loading state | | error | unknown \| null | null | Signals error state when truthy | | empty | boolean | false | Signals empty state |

Returns: 'loading' | 'error' | 'empty' | 'content'

useKeyboardInsets

Tracks keyboard visibility and height. Works standalone — no provider needed.

| Field | Type | Description | | --- | --- | --- | | visible | boolean | Whether the keyboard is currently visible | | keyboardHeight | number | Raw keyboard height from native events | | bottom | number | Keyboard bottom inset after safe area adjustment | | animationDuration | number | Keyboard animation duration (iOS only) |

Uses keyboardWillShow / keyboardWillHide on iOS and keyboardDidShow / keyboardDidHide on Android.

Customization

Global defaults via ScreenSystemProvider

Set once at the app root. All screens inherit these automatically.

<ScreenSystemProvider
  keyboardVerticalOffset={44}
  actionBarBottomGap={0}
  defaultKeyboardBehavior="padding"
  defaultActionBarKeyboardBehavior="padding"
>
  <RootApp />
</ScreenSystemProvider>

keyboardVerticalOffset is useful when your navigation header contributes extra height that affects keyboard offset calculations.

Per-screen keyboard behavior override

Each screen can override the global defaults:

<ScreenContainer
  keyboardAware
  keyboardBehavior="margin"
  keyboardVerticalOffset={60}
>
  {/* ... */}
</ScreenContainer>

Custom safe area handling

Use overrides when you manage safe area outside the component:

<ScreenContainer
  includeTopInset={false}
  includeBottomInset={false}
  topInsetOverride={0}
  bottomInsetOverride={0}
>
  {/* ... */}
</ScreenContainer>

Add extra spacing on top of the computed inset:

<ScreenContainer
  includeTopInset
  extraTopInset={8}
  includeBottomInset
  extraBottomInset={16}
>
  {/* ... */}
</ScreenContainer>

Explicit focus order with gaps

Leave gaps in the order sequence so you can insert fields later without renumbering:

const firstName = useFocusableField({ id: 'firstName', order: 10 });
const lastName  = useFocusableField({ id: 'lastName',  order: 20 });
const email     = useFocusableField({ id: 'email',     order: 30 });
const phone     = useFocusableField({ id: 'phone',     order: 40, submitBehavior: 'blur' });

Conditional fields

Mark a field as disabled to skip it in focus navigation without unmounting:

const altEmail = useFocusableField({
  id: 'altEmail',
  order: 35,
  disabled: !showAltEmail, // skipped when the field is hidden
});

Custom scroll offset per field

Override the global scroll offset for a specific field that needs more breathing room:

const longAnswer = useFocusableField({
  id: 'longAnswer',
  order: 50,
  scrollToFocusedInput
  Offset: 48,
});

Focusing the first invalid field on submit

Use useFocusController to drive form validation UX:

const { focusFirstInvalid } = useFocusController();

function handleSubmit() {
  const invalid = validate(); // returns string[] of invalid field ids
  if (invalid.length > 0) {
    focusFirstInvalid(invalid);
    return;
  }
  submit();
}

Screen state rendering

Wire loading / error / empty states without if-else chains:

function ProductScreen() {
  const { data, isLoading, error } = useProduct(id);

  return (
    <ScreenStateView
      loading={isLoading}
      error={error}
      empty={data?.items.length === 0}
      renderLoading={() => <Spinner />}
      renderError={(err) => <ErrorView error={err} />}
      renderEmpty={() => <EmptyState />}
    >
      <ProductList items={data.items} />
    </ScreenStateView>
  );
}

Examples

Full runnable examples are in example/:

| File | What it shows | | --- | --- | | ProviderAndLayoutExample.tsx | Provider setup and layout defaults | | FormFlowExample.tsx | Multi-step keyboard-aware form | | FocusControllerExample.tsx | Imperative focus control | | ScrollCoordinatorExample.tsx | Scroll coordinator with multiple inputs | | ScreenStatesExample.tsx | Loading / error / empty / content states | | KeyboardInsetsExample.tsx | Live keyboard inset inspection |

See example/README.md for the full breakdown.

Contributing

Contributions are welcome.

Suggested workflow:

1. Fork the repository or create a feature branch.
2. Make focused changes.
3. Run npm run build and npm run typecheck.
4. Update docs or examples when behavior changes.
5. Open a pull request with a clear summary of the change.

See CONTRIBUTING.md for more detail.

Roadmap

See PLAN.md.

License

MIT. See LICENSE.