Vega WebView Component Reference

To set up to use WebView, see Overview of Vega Web Apps.

Props

source

Loads the given URI with optional headers. The source object has the following sub properties.

• uri (string): The URI to load on the WebView.
• headers (object): Additional HTTP headers to send with the request.

Here is an example.

<WebView
    source ={{
        uri: "http://amazon.com/",
        headers: { "custom-app-header": "react-native-webview-app", "custom-app-header2": "VALEU2" }}}/>

onLoad

After WebView loads the web page, it calls onLoad. Here is an example.

<WebView
  source={{ uri: 'https://amazon.com' }}
  onLoad={(event) => {
    console.log('url: ', event.nativeEvent.url)
  }}/>

When you call the onLoad function pass the following properties:

Copy code Copied to clipboard.

url(str) - loaded URL in the WebView.
canGoBack(bool) - WebView has history to go back.
canGoForward(bool) - WebView has history to go forward.

onLoadStart

When WebView starts loading resources, it calls onLoadStart. Here is an example.

<WebView
  source={{ uri: 'https://amazon.com' }}
  onLoadStart={(event) => {
    console.log('url: ', event.nativeEvent.url)
  }}/>

When calling onLoadStart pass the following properties.

{% include copybutton.html id="ThkIR8NY" %}

url(str) - loaded url in the WebView.
canGoBack(bool) - WebView has history to go back.
canGoForward(bool) - WebView has history to go forward.

onError

When the WebView fails to load the API calls onError.

<WebView
  source={{ uri: 'https://amazon.com' }}
  onError={(event) => {
    console.log('url: ', event.nativeEvent.url)
  }}/>

When calling the onError function pass the following properties.

url(str) - loaded url in the WebView.
canGoBack(bool) - WebView has history to go back.
canGoForward(bool) - WebView has history to go forward.
code(int)  - error code.
description(str) - error description.

onHttpError

When WebView fails to load it throw an onHttpError HTTP status error and the API calls the the onHttpError function.

Any statusCodes >= 400 is an HTTP status error.

The isMainFrame flag identifies whether an error occurred when loading the main page, or a dependent resource. This will be true for main frame and false for subresources or iframes.

Here is an example.

<WebView
  source={{ uri: 'https://example.com' }}
  onHttpError={(event) => {
    console.log('url: ', event.nativeEvent.url)
    console.log("HttpError statusCode, description, isMainFrame: ",
                  event.nativeEvent.statusCode,
                  event.nativeEvent.description,
                  event.nativeEvent.isMainFrame );
  }}/>

When calling the onHttpError function pass the following properties.

Copy code Copied to clipboard.

url
canGoBack
canGoForward
statusCode
description
isMainFrame

onCloseWindow

This function notifies the host app to close the given WebView and remove it from the view system.

Since any WebView interaction after this call might result in unexpected behavior, the host app should destroy the WebView instance after receiving this call.

There is no default functionality for this method.

Here is an example.

import React, { BackHandler } from 'react-native'; 
<WebView 
  source={{ uri : 'https://example.com/' }} 
  onCloseWindow={ 
    () => { // Handle the close event raised from the loaded webpage BackHandler.exitApp() }
   } />

onMessage

Invoked when the WebView JS calls ReactNativeWebView.postMessage. It accepts one argument and is available to the event object. The data must be a string.

Here is an example.

<WebView
  source={{ uri: 'https://amazon.com' }}
  onMessage={(event) => {
    console.log("data: ", event.nativeEvent.data);
  }}/>

onShouldStartLoadWithRequest

onShouldStartLoadWithRequest allows custom handling of any WebView requests. A return of true continues loading the request and false to stops loading. Here is an example.

<WebView
  source={{ uri: 'https://amazon.com' }}
  onShouldStartLoadWithRequest={(request) => {
        return request.url.startsWith('https://amazon.com');
  }}/>

This onShouldStartLoadWithRequest object can contain the following properties.

{% include copybutton.html id="qwyJ7XuF" %}

url(str) - loaded url in the WebView.
canGoBack(bool) - WebView has history to go back.
canGoForward(bool) - WebView has history to go forward.
lockIdentifier(int) - lock identifier number for JS and native sync.

onClientCertAuthentication (optional)

This optional function enables a host app to manage client certificate authentication requests.

Parameters

• This gives you the details of the authentication request.

  Copy code Copied to clipboard.

  request (Type: ClientCertAuthenticationRequest)
  

• This callback object has a function to handle authentication.

  Copy code Copied to clipboard.

  callback (Type: ClientCertAuthenticationCallback)
  

Callback Functions

• This function handles the client certificate authentication when the certificate is in PKCS#12 format.

  Copy code Copied to clipboard.

    handleWithPkcs12(certificateData: Pkcs12CertificateData)
  

• This function cancels the client certificate authentication process.

  Copy code Copied to clipboard.

    cancel()
  

The default behavior is to cancel the request without a client certificate.

Here is an example.

<WebView
  source={{ uri: 'https://amazon.com' }}
  onClientCertAuthentication={(request, callback) => {

      // To handle with authentication:
      callback.handleWithPkcs12({
            certificate: "base64-certificate",
            password: "certificate-password",
      });

      // To decline the request:
      callback.cancel();
  }}/>

The request object contains the following properties:

• hostName - The server's host name.
• portNumber - The port number for the request.

onSslError (optional)

This optional function notifies the host app that an SSL error occurred when it was loading a resource. The host app must call either SslErrorHandler.cancel() or SslErrorHandler.proceed(). By default, it rejects when an SSL error occurs when loading the URL.

Users can call the proceed() or cancel() methods to respond to future SSL errors. By default one of these fuctions cancels the resource loading process. This function is called only for recoverable SSL certificate errors, such as untrusted certifier, certificate expiration, or self-signed. For non-recoverable errors, such as when the server fails the client, WebView calls onError(WebView, WebResourceRequest, WebResourceError) with the ERROR_FAILED_SSL_HANDSHAKE (-11) argument.

Here is an example.

const handleSSLError = (sslError: SslErrorData , callback: OnSslErrorCallback) => {
    console.log("WebViewClient: ", sslError.url, sslError.code, sslError description);
    // so keeping some delay, assuming it might take sometimes to load the resource, and user to select.
    setTimeout(() => {
    // to accept the SSL error.
    callback.proceed();
    // to reject the SSL error
    // callback.cancel();
    }, 5000);
}
  <WebView
      source={{ uri: 'https://self-signed.badssl.com/' }}
      onSslError={(sslError: SslErrorData , callback: OnSslErrorCallback) => {
      HandleSSLError(sslError, sslErrorHandler);
  }}/>

SslErrorData objects

The SslErrorData object contains the following properties:

• url
• code
• description

The OnSslErrorCallback object contains the following methods:

• proceed() allows an SSL error.
• cancel() Rejects an SSL error.

javaScriptEnabled

A Boolean value to enable or disable JavaScript in WebView. The default value is true.

Here is an example.

<WebView
  source={{ uri: 'https://amazon.com' }}
  javaScriptEnabled={true}/>

domStorageEnabled

A Boolean value to enable or disable DOM Storage (local web storage) in WebView. The default is false.

Here is an example.

<WebView
  source={{ uri: 'https://amazon.com' }}
  domStorageEnabled={true}/>

userAgent

Sets user-Agent for WebView.

Here is an example.

<WebView
  source={{ uri: 'https://amazon.com' }}
  userAgent={"custom-user-agent"}/>

mixedContentMode

Specifies mixed content mode for the WebView.

Here is an example.

<WebView
  source={{ uri: 'https://amazon.com' }}
  mixedContentMode = {'always'}
  }/>

Possible values for mixedContentMode are the following.

1. Never (default), which uses MIXED_CONTENT_NEVER_ALLOW WebView doesn't allow a secure origin to load content from an insecure origin. Consider this mode because it is the most secure.
2. Always, which uses MIXED_CONTENT_ALWAYS_ALLOW. WebView allows a secure origin to load content from any other origin, even if that origin is insecure. Amazon doesn't recommend this because it is the least secure.
3. Compatibility, which uses MIXED_CONTENT_COMPATIBILITY_MODE. WebView attempts to be compatible with the approach used by a modern web browser with regard to mixed content. WebView might allow some insecure content from a secure origin and when other types of content are blocked. The types of content that Webview allows or blocks might change release to release and are not explicitly defined. This mode is intended for apps that don't control their own rendered content but requrie some reasonable security. For the highest security, use MIXED_CONTENT_NEVER_ALLOW.

allowFileAccess

A Boolean value to enable or disable access to the file system using file:// URI's. The default value is false.

Here is an example.

<WebView
  source={{ uri: 'file:///<Path to file>' }}
  allowFileAccess = {true}/>

allowSystemKeyEvents

This Boolean determines whether the app listens for special system key events like "back" button(keyCode: 27) in their web JavaScript layer. This functionality helps developers keep their business logic on the website instead of relying on React Native for Vega app code.

When this property is true, the system delivers key events in web JavaScript and not in React Native for Vega app code. Only the most recent WebView instance will receive system key events, even if other WebView instances are on the screen.

Here is an example.

<WebView
  source={{ uri: 'https://amazon.com' }}
  allowSystemKeyEvents={true}/>

mediaPlaybackRequiresUserAction

A Boolean value to determine whether HTML5 audio and video requires a user to gesture before it starts playing. The default value is true.

Here is an example.

<WebView
  source={{ uri: 'https://amazon.com' }}
  mediaPlaybackRequiresUserAction = {false}/>

thirdPartyCookiesEnabled

A Boolean value to enable or disable third party cookies in WebView. The default is true, but it will be false in the future.

Here is an example.

<WebView
  source={{ uri: 'https://amazon.com' }}
  thirdPartyCookiesEnabled={false}/>

allowsDefaultMediaControl

Allows the VegaMediaControl events to be automatically bridged to the active WebView media session. This allows seamless integration of voice commands for the WebView. For more details, see Vega Media Controls Overview.

• true enables the default media transport controls for the WebView media session, such as play, pause, seek forward, seek backward.
• false disables the default media transport controls.

Considerations:

• This setting affects all media content types including advertisements and live streams.
• For granular control over media content, see Overriding default media control handlers.

Here is an example.

<WebView
  source={{ uri: 'https://amazon.com' }}
  allowsDefaultMediaControl={true}/>

Methods

injectJavaScript

injectJavaScript evaluates the JavaScript string in WebView.

Here is an example.

const webRef = useRef(null);
webRef.current.injectJavaScript('alert("Hello world")');

<WebView
  source={{ uri: 'https://amazon.com' }}
  ref={webRef}/>

stopLoading

This stops loading the current page.

Here is an example.

const webRef = useRef(null);
<WebView
  source={{ uri: 'https://amazon.com' }}
  onLoadStart={(event) => {
    webRef.current.stopLoading();
  }}
  ref={webRef}/>

clearCache(bool)

Clears the resource cache. The cache is per app, so clearCache clears the cache for all WebView parts of the same app. If the argument is true, it includes disk files. If the argument is false, it clears only the RAM cache.

Here is an example.

const webRef = useRef(null);

<WebView
  source={{ uri: 'https://amazon.com' }}
  ref={webRef}
  onLoad={(event) => {
    webRef.current.clearCache(true);
  }}/>

goBack()

Goes back one page in the WebView history. If there are no items in the history, this function will perform no operations (no-op) and return.

Here is an example.

const webRef = useRef(null);

<View style={{ flex: 1 }}>
  <Button
    title="GoBack"
    onPress={() => { if (webRef.current) { webRef.current.goBack(); }}}
  />
  <WebView
    source={{ uri: 'https://amazon.com' }}
    ref={webRef}
  />
</View>

goForward()

Goes forward one page in the WebView history. If there are no item in the history to go forward, this function will perform no operations (no-op) and return.

Here is an example.

 const webRef = useRef(null);

 <View style={{ flex: 1 }}>
   <Button
     title="Go Forward"
     onPress={() => { if (webRef.current) { webRef.current.goForward(); } }}
   />
   <WebView
     source={{ uri: 'https://example.com' }}
     ref={webRef}
   />
 </View>

clearHistory()

Clears the internal back/forward history for the WebView instance.

Here is an example.

 const webRef = useRef(null);

 <View style={{ flex: 1 }}>
   <Button
     title="Clear History"
     onPress={() => { if (webRef.current) { webRef.current.clearHistory(); } }}
   />
   <WebView
     source={{ uri: 'https://example.com' }}
     ref={webRef}
   />
 </View>

dispatchTouchEvent(event: TouchEvent)

Dispatches a touch event to the specified target web element. It allows you to programmatically raise touch events such as touchstart and touchend.

Parameters

event: A TouchEvent object representing dispatched touch. This object contains information about the type of touch event (type) and an array of touch points associated with the event (touches).

Here is an example.

  const webRef = useRef(null);

  <View style={{ flex: 1 }}>
    <Button
        title="Trigger Touch"
        onPress={() =>{
          const touches: Touch[] = [ { clientX: 100, clientY: 200 }];
          // Create a new TouchEvent object
          const touchStartEvent = new TouchEvent("touchstart", { touches });
          webRef.current && webRef.current.dispatchTouchEvent(touchStartEvent)
          // Create a new TouchEvent object
          const touchEndEvent = new TouchEvent("touchend", { touches });
          webRef.current && webRef.current.dispatchTouchEvent(touchEndEvent)}
        }
    />
    <WebView
      source={{ uri: 'https://amazon.com' }}
      ref={webRef}
    />
  </View>

scrollBy(offsetX: number, offsetY: number)

Scrolls the content of the WebView by the specified offset values. This method allows you to programmatically scroll the content of the WebView by a specified horizontal (offsetX) and vertical (offsetY) offset.

Parameters

• offsetX: A number representing the horizontal offset by which to scroll the content. A positive value scrolls the content to the right, when a negative value scrolls it to the left.
• offsetY: A number representing the vertical offset by which to scroll the content. A positive value scrolls the content downwards, when a negative value scrolls it upwards.

Here is an example.

  const webRef = useRef(null);

  <View style={{ flex: 1 }}>
    <Button
      title="Scroll Down"
      onPress={() => { if (webRef.current) { webRef.current.scrollBy(0, 100); } }}
    />
    <WebView
      source={{ uri: 'https://amazon.com' }}
      ref={webRef}
    />
  </View>

getVisualViewportInfo()

Retrieves information about the visual viewport of the WebView.

Returns

An object containing information about the visual viewport, including:

• height: The height of the visual viewport.
• width: The width of the visual viewport.
• offsetTop: The offset from the top of the visual viewport to the top of the content.
• offsetLeft: The offset from the left of the visual viewport to the left of the content.

Here is an example.

  const webRef = useRef(null);

  const handleWebViewLoad = (event: WebViewNavigationEvent) => {
      console.log(" getVisualViewportInfo: ", webRef.current.getVisualViewportInfo());
  };

  <View style={{ flex: 1 }}>
    <WebView
      source={{ uri: 'https://example.com' }}
      onLoad = {handleWebViewLoad}
      ref={webRef}
    />
  </View>

getContentSizeInfo()

Retrieves information about the size of the content within the WebView.

Returns

An object containing information about the content size, including:

• scrollWidth: The total width of the content.
• scrollHeight: The total height of the content.

Here is an example.

  const webRef = useRef(null);

  const handleWebViewLoad = (event: WebViewNavigationEvent) => {
      console.log(" getContentSizeInfo: ", webRef.current.getContentSizeInfo());
  };

  <View style={{ flex: 1 }}>
    <WebView
      source={{ uri: 'https://example.com' }}
      onLoad = {handleWebViewLoad}
      ref={webRef}
    />
  </View>

reload()

This method reloads the current page of the WebView instance.

Here is an example.

 const webRef = useRef(null);

 <View style={{ flex: 1 }}>
  <Button
    title="Reload"
    onPress={() => { if (webRef.current) { webRef.current.reload(); } }}
  />
  <WebView
    source={{ uri: 'https://example.com' }}
    ref={webRef}
  />
 </View>

Related topics

• Overview of Vega Web Apps
• Vega WebView Cookie Manager

Last updated: Nov 13, 2025