feat!: customizable backdrop (color, style, or custom component)

[arekkubaczkowski]

Closes #45.

custom-backdrop.mov

The shared backdrop's appearance was hardcoded to rgba(0, 0, 0, 0.5), and the only knob anywhere in the public API was backdrop: false on open(), which turned it off entirely. Theming, blur, and per-sheet variation all required either patching the package or rendering your own backdrop inside the sheet — which loses everything the shared one provides: stack-aware z-indexing, living outside the BottomSheetScaleView transform, and being driven from the sheet's live animatedIndex.

This makes what the backdrop renders configurable while leaving all of that behaviour with the manager.

API

Two levels, the sheet's choice winning over the group's:

// Group default — same prop name and type as on the adapters
<BottomSheetManagerProvider
  id="default"
  backdrop={{ kind: 'styled', style: { backgroundColor: 'rgba(0,0,0,0.75)' } }}
>

// Per sheet — on any shipped adapter, in inline, portal and persistent mode alike
<GorhomSheetAdapter backdrop={{ kind: 'styled', style: { backgroundColor: 'rgba(0,0,0,0.2)' } }} />
<CustomModalAdapter backdrop={{ kind: 'custom', component: BlurBackdrop }} />
<SwmansionSheetAdapter backdrop={false} />

type BackdropConfig =
  | { kind: 'styled'; style?: StyleProp<ViewStyle>; pressToDismiss?: boolean }
  | { kind: 'custom'; component: ComponentType<BackdropComponentProps>; pressToDismiss?: boolean };

type BackdropComponentProps = {
  sheetId: string;
  /** -1 hidden → 0 visible — the same shared value the built-in backdrop interpolates. */
  animatedIndex: SharedValue<number>;
  /** Routes through requestClose, so onBeforeClose interceptors still run. */
  close: () => void;
};

A discriminated union rather than three mutually-exclusive optional fields, mirroring OpenPayload — kind is what callers reason about. A custom component receives the raw animatedIndex rather than a pre-computed opacity, so blur intensity or a gradient can be driven from the sheet's real position on the UI thread; it therefore owns its own fade, and the built-in opacity is deliberately not applied on top.

Resolution is atomic for the visual choice — a sheet-level config replaces the group's rendering entirely, so a group custom component never bleeds under a sheet that asked for a styled scrim. Styles compose (default → group → sheet) where both levels are styled, and pressToDismiss resolves per field.

Adapter authors get useAdapterBackdrop(id, backdrop) and AdapterBackdropProps, which is exactly what the five shipped adapters use.

Breaking changes

1. backdrop?: boolean removed from open() options (useBottomSheetManager, useBottomSheetControl).

open(<MySheet />, { backdrop: false });   // before
<GorhomSheetAdapter backdrop={false}>     // after, in MySheet's JSX

Declaring it on the adapter works identically across all three operating modes, and keeping open() out of the field is what lets a persistent sheet's backdrop survive close/re-open cycles. The capability that genuinely moves is per-open variation — the migration guide shows the params route.

2. backdropComponent removed from GorhomSheetAdapterProps. The manager always renders the backdrop, so the two can never stack. Passing gorhom's own silently disabled the stack-aware one and substituted a per-sheet backdrop that does not participate in the stack — a bug shaped like a feature. backdrop={{ kind: 'custom', component }} replaces it.

Both are documented under Backdrop → Migration. This lands as 3.0.0.

Testing

117 tests pass (24 new), plus typecheck, lint, and a docs build with onBrokenLinks: 'throw'.

Per CLAUDE.md's "write the test so it fails without the fix", each new test was confirmed to fail against the unfixed code. The ones worth calling out cover decisions that would otherwise silently regress:

• a value-equal fresh object literal produces no store write — merging useAdapterBackdrop's two effects into the obvious one-effect-with-cleanup form passes every other test
• restyling does not re-render the memoized sheet layer (QueueItem subscribes to a stable 'off' | 'own' | 'inherit' primitive, never the config object)
• a config style's own opacity does not replace the manager's fade
• a style carrying an explicit undefined is not mistaken for one carrying a real value in its place
• a persistent sheet keeps its backdrop across a full close/re-open cycle
• tap routes through requestClose, so a refusing onBeforeClose interceptor keeps the sheet open

Review notes

The implementation was reviewed by four independent agents (API design, correctness, readability/DRY, docs-vs-code accuracy). Findings that survived verification are folded into the commits above — the substantive ones were the equality false-positive, the opacity ordering, a one-frame flash of a group-level custom backdrop (now applied in a layout effect), and the two untested design decisions listed above.

🤖 Generated with Claude Code