Vega Web App Component Reference

If you want to get set up to use WebView, see Set Up your Vega Web App.

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 invokes onLoad. Here is an example.

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

The onLoad function is invoked with 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 invokes onLoadStart. Here is an example.

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

onLoadStart is invoked with 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

onError is invoked when WebView fails to load.

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

The onError function is invoked with 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

The onHttpError function is invoked when WebView fails to load causing this http status error.

Any statusCodes >= 400 is an HTTP status error.

The isMainFrame flag indentifies whether an error occurred while 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 );
  }}/>

The onHttpError function is invoked with 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 may 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 application 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 application that an SSL error occurred while it was loading a resource. The host application must call either SslErrorHandler.cancel() or SslErrorHandler.proceed(). By default, it rejects when an SSL error occurs while loading the URL.

Users may call the proceed() or cancel() method to respond to future SSL errors. By default, the resource loading process is canceled. 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. We recommend this mode since 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. We don't recommend this since 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. Some insecure content may be allowed to be loaded by a secure origin and other types of content will be blocked. The types of content are allowed or blocked may change release to release and are not explicitly defined. This mode is intended for apps that don't control their own rendered content but desire some reasonably 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 application code.

When this property is true, the system delivers key events in web JavaScript and not in React Native for Vega application 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 application, so clearCache clears the cache for all WebView parts of the same application. 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 trigger 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, while 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, while 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

• Vega Web App Overview
• Set Up your Vega Web App
• Develop Your Vega Web App

Last updated: Sep 30, 2025