WebView#

Native web view that embeds web content in your app — WKWebView on iOS, android.webkit.WebView on Android. Load a remote URL or inline HTML, react to load and error events, and pass messages both ways between the page and your app.

Import#

import { WebView } from '@sigx/lynx-webview';

Importing the package entry also registers the underlying sigx-webview JSX intrinsic, so the component is the only import you need. There is no manual native setup — sigx prebuild auto-links the module once you add the dependency.

Basic Usage#

Set src to a remote URL and listen for the load lifecycle with onLoad / onError. src accepts http(s): and about:blank URLs only — javascript: and file: schemes are refused.

import { WebView } from '@sigx/lynx-webview';

<WebView
  src="https://example.com"
  onLoad={(e) => console.log('loaded', e.detail.url)}
  onError={(e) => console.warn('failed', e.detail.message)}
/>;

To render local or richer markup, use html instead. Inline HTML loads with a null base URL, so the page is fully sandboxed and relative URLs do not resolve. Set src or html, but not both — setting both is undefined behavior.

import { WebView } from '@sigx/lynx-webview';

<WebView html="<h1>Hello from sigx-lynx</h1>" />;

Load and Error Events#

onLoad fires once the main-frame navigation finishes; onError fires when the main frame fails (DNS, TLS, or unreachable host). Subresource failures — a missing favicon, a 404 image — are suppressed, so onError only signals a genuinely failed page.

import { component } from '@sigx/lynx';
import { signal } from '@sigx/core';
import { WebView } from '@sigx/lynx-webview';

const Screen = component(() => {
  const status = signal<'loading' | 'ready' | 'failed'>('loading');

  return () => (
    <view>
      <WebView
        src="https://en.wikivoyage.org/wiki/Lisbon"
        style={{ width: '100%', height: '100%' }}
        onLoad={(e) => {
          console.log('finished', e.detail.url);
          status.set('ready');
        }}
        onError={(e) => {
          console.warn('failed for', e.detail.url, '-', e.detail.message);
          status.set('failed');
        }}
      />
    </view>
  );
});

Messaging#

The native side injects a bridge user-script at document start. The page can call window.sigx.postMessage(payload), which surfaces on onMessage as e.detail.data. The value is always a string on the wire — objects are JSON-stringified before delivery, so parse structured payloads on the receiving side.

import { WebView } from '@sigx/lynx-webview';

<WebView
  html={pageHtml}
  onMessage={(e) => {
    const data = JSON.parse(e.detail.data);
    // data.click === 'hi'
  }}
/>;

For the reverse direction (app to page), capture the native element with mtRef and call WebViewMethods.postMessage; the page receives it through window.sigx.onmessage.

Driving It Imperatively#

Pass a MainThreadRef through mtRef to capture the native element, then drive navigation with the WebViewMethods wrappers (goBack, goForward, reload, stopLoading, canGoBack, canGoForward, injectJavaScript, postMessage). Each method accepts el | null and no-ops when null.

import { useMainThreadRef, type MainThread } from '@sigx/lynx';
import { WebView } from '@sigx/lynx-webview';

const ref = useMainThreadRef<MainThread.Element | null>(null);

const onBack = () => {
  'main thread';
  ref.current?.invoke('goBack', {});
};

<WebView mtRef={ref} id="my-webview" src="https://example.com" />;
<view main-thread:bindtap={onBack}><text>Back</text></view>;

See the usage guide for background-thread (SelectorQuery) and runOnMainThread patterns.

Props#

All props are optional. See WebViewProps for the full type.

Events#

See also#

• API reference — every export with its full signature.
• Usage guide — practical patterns and platform notes.