feat: add loadingContainerStyle prop for improved loading state handling

Co-authored-by: Copilot <copilot@github.com>

Author: mCodex

README.md

@@ -39,7 +39,7 @@ Three defaults changed in the 1.1.x line. Each is a one-line migration:
 - 🛡️ Sanity guard clamps runaway heights and retries with the last good value, so flaky pages never lock your layout.
 - 🧵 Keeps the WebView scroll-disabled so outer `ScrollView`s and gesture handlers stay silky smooth.
 - 🎨 Transparent background by default; style the container however you like.
-- ⚙️ Friendly API with `minHeight`, `containerStyle`, and `onHeightChange` callbacks.
+- ⚙️ Friendly API with `minHeight`, `containerStyle`, `loadingContainerStyle`, and `onHeightChange` callbacks.
 - 🌲 ESM-first build, fully typed, `sideEffects: false` for optimal tree shaking.
 - 📱 Verified on iOS, Android, and Expo Go out of the box.
 
@@ -100,6 +100,7 @@ The example showcases:
 | --- | --- | --- | --- |
 | `minHeight` | `number` | `0` | Minimum height (dp) applied to the container. When `0`, the container is unsized until the first measurement arrives (avoids layout flicker and the iOS 26 WKWebView 1px feedback loop). |
 | `containerStyle` | `StyleProp<ViewStyle>` | — | Styles applied to the wrapping `View`. Use it for padding, borders, or shadows. Do not set `height` — it is managed by the hook. |
+| `loadingContainerStyle` | `StyleProp<ViewStyle>` | — | Styles applied to the wrapping `View` **only while height is still being measured** (i.e. while the bridge has not yet reported a value). Use `{ flex: 1 }` inside a `ScrollView` with `contentContainerStyle={{ flexGrow: 1 }}` so the native activity indicator is never clipped. Dropped automatically once the first measurement commits. |
 | `onHeightChange` | `(height: number) => void` | — | Callback fired whenever a new height is committed. Great for analytics or debugging. Never fires for invalid or out-of-range values. |
 | `originWhitelist` | `string[]` | `['http://*', 'https://*']` | Origins the WebView is allowed to navigate to. Blocks non-web schemes (`file:`, `javascript:`, `data:`, `intent:`) by default. Tighten it to a specific origin list for stricter environments. |
 | `javaScriptEnabled` | `boolean` | `true` | When `false`, the auto-height bridge is **not** injected and the container falls back to `minHeight`. Use for static HTML that doesn't need JS. |
@@ -108,6 +109,26 @@ The example showcases:
 > [!NOTE]
 > 🧩 `scrollEnabled` defaults to `false` so sizing remains deterministic. Only enable it if the WebView should manage its own scroll.
 
+### Loading state inside a `ScrollView`
+
+When `minHeight` is `0` (the default), the container has no height until the bridge reports the first measurement. Inside a `ScrollView` this means the native loading spinner is rendered in a 0 dp frame and gets clipped.
+
+Fix it with `loadingContainerStyle`:
+
+```tsx
+<ScrollView contentContainerStyle={{ flexGrow: 1 }}>
+  <SizedWebView
+    source={{ uri: 'https://example.com/article' }}
+    loadingContainerStyle={{ flex: 1 }}
+    containerStyle={{ borderRadius: 12, overflow: 'hidden' }}
+    renderLoading={() => <ActivityIndicator size="large" style={{ flex: 1 }} />}
+  />
+</ScrollView>
+```
+
+- During loading: container is `[{ flex: 1 }, containerStyle]` — fills the scroll area, spinner is fully visible.
+- After measurement: container becomes `[{ height: N }, containerStyle]` — shrinks to content height, `loadingContainerStyle` is dropped.
+
 ## 🛡️ Security
 
 - **Namespaced message protocol.** The injected bridge posts values prefixed with `__RN_SIZED_WV__:` and the hook rejects everything else, so your own `onMessage` traffic cannot accidentally (or maliciously) mutate the container height.

src/__tests__/index.test.tsx

@@ -73,7 +73,6 @@ describe('SizedWebView', () => {
 
     expect(props.style).toEqual([
       { backgroundColor: 'transparent' },
-      { flex: 1, width: '100%' },
       { opacity: 0.5 },
     ]);
     expect(props.originWhitelist).toEqual(['http://*', 'https://*']);
@@ -291,4 +290,53 @@ describe('SizedWebView', () => {
       renderResult.unmount();
     });
   });
+
+  it('applies loadingContainerStyle to the container while height is undefined', () => {
+    const { useAutoHeight, __setHeightFromPayload } = jest.requireMock(
+      '../hooks/useAutoHeight'
+    );
+    (useAutoHeight as jest.Mock).mockReturnValue({
+      height: undefined,
+      setHeightFromPayload: __setHeightFromPayload,
+    });
+
+    const renderResult = render(
+      <SizedWebView
+        source={{ html: '<p>Hi</p>' }}
+        loadingContainerStyle={{ flex: 1 }}
+        containerStyle={{ backgroundColor: 'blue' }}
+      />
+    );
+
+    const container = renderResult.UNSAFE_getByType(View);
+    expect(container.props.style).toEqual([
+      { flex: 1 },
+      { backgroundColor: 'blue' },
+    ]);
+
+    act(() => {
+      renderResult.unmount();
+    });
+  });
+
+  it('does not include loadingContainerStyle once height is committed', () => {
+    const renderResult = render(
+      <SizedWebView
+        source={{ html: '<p>Hi</p>' }}
+        loadingContainerStyle={{ flex: 1 }}
+        containerStyle={{ backgroundColor: 'green' }}
+      />
+    );
+
+    // Default mock returns height: 240 — measurement is already committed.
+    const container = renderResult.UNSAFE_getByType(View);
+    expect(container.props.style).toEqual([
+      { height: 240 },
+      { backgroundColor: 'green' },
+    ]);
+
+    act(() => {
+      renderResult.unmount();
+    });
+  });
 });

src/components/SizedWebView.tsx

@@ -30,6 +30,29 @@ export interface SizedWebViewProps extends WebViewProps {
    */
   containerStyle?: StyleProp<ViewStyle>;
 
+  /**
+   * Style applied to the wrapping `View` only while the content height is
+   * still being measured (i.e. while `height` is `undefined`).
+   *
+   * Use this to keep the container visible during loading so the native
+   * activity indicator is never clipped. A common pattern:
+   *
+   * ```tsx
+   * // Inside a ScrollView with contentContainerStyle={{ flexGrow: 1 }}
+   * <SizedWebView
+   *   source={source}
+   *   loadingContainerStyle={{ flex: 1 }}
+   * />
+   * ```
+   *
+   * Once the first height measurement is committed, this style is dropped and
+   * `containerStyle` + the measured `{ height }` take full effect. Setting
+   * this on the **outer container** (not the inner WebView) is safe — the
+   * injected wrapper `div` has `height: auto` and no `overflow: hidden`, so
+   * `wrapper.scrollHeight` is never clamped by the native frame size.
+   */
+  loadingContainerStyle?: StyleProp<ViewStyle>;
+
   /**
    * Fires after each committed auto-height change. Values are rAF-batched and
    * clamped to a sane upper bound for safety.
@@ -56,7 +79,6 @@ const WEBVIEW_DEFAULTS = {
 } satisfies Partial<WebViewProps>;
 
 const TRANSPARENT_WEBVIEW_STYLE = { backgroundColor: 'transparent' as const };
-const MEASURED_WEBVIEW_STYLE = { flex: 1, width: '100%' as const };
 
 /**
  * A `react-native-webview` that sizes itself to match its rendered HTML.
@@ -73,6 +95,7 @@ const SizedWebViewImpl = (props: SizedWebViewProps) => {
   const {
     minHeight = 0,
     containerStyle,
+    loadingContainerStyle,
     style,
     injectedJavaScript,
     injectedJavaScriptBeforeContentLoaded,
@@ -124,18 +147,16 @@ const SizedWebViewImpl = (props: SizedWebViewProps) => {
 
   const containerStyles = useMemo<StyleProp<ViewStyle>>(() => {
     if (height == null) {
-      return containerStyle;
+      return loadingContainerStyle != null
+        ? [loadingContainerStyle, containerStyle]
+        : containerStyle;
     }
     return [{ height }, containerStyle];
-  }, [containerStyle, height]);
+  }, [containerStyle, height, loadingContainerStyle]);
 
   const webViewStyles = useMemo(
-    () => [
-      TRANSPARENT_WEBVIEW_STYLE,
-      height == null ? undefined : MEASURED_WEBVIEW_STYLE,
-      style,
-    ],
-    [height, style]
+    () => [TRANSPARENT_WEBVIEW_STYLE, style],
+    [style]
   );
 
   return (