Control WebView Properties

In this document, to control how WebView behaves apps-in-toss.config.tsthat can be configured in webView we'll explain the options.

things like scroll behavior, media playback behavior, and whether gestures are used WebView properties that directly affect the user experiencecan be adjusted to fit your service.

Supported environments

• Runtime environment: WebView, Toss app
• SDK version: WebView 3.x or later

How to configure WebView properties

WebView properties are apps-in-toss.config.ts in the file's webView item.

import { defineConfig } from '@apps-in-toss/web-framework/config';

export default defineConfig({
  webView: {
    // WebView behavior-related options
  },
});

In SDK 2.x, granite.config.tsand webViewPropswere each renamed in SDK 3.x to apps-in-toss.config.ts, webViewwere renamed. The sub-options are the same.

Available WebView properties

webViewyou can set the following properties.

webView?: {
  allowsInlineMediaPlayback?: boolean;
  bounces?: boolean;
  pullToRefreshEnabled?: boolean;
  overScrollMode?: 'always' | 'content' | 'never';
  mediaPlaybackRequiresUserAction?: boolean;
  allowsBackForwardNavigationGestures?: boolean;
};

Allow inline media playback (allowsInlineMediaPlayback)

sets whether HTML5 videos are played inline inside the WebView instead of in full screen.

This is an iOS-only property, trueafter setting it to <video> tag, webkit-playsinline the webkit-playsinline attribute is required for inline playback.

Item	Contents
Type	boolean
Default	false
Platform	iOS

Use scroll bounce effect (bounces)

sets whether to use the bounce effect when reaching the edge of the scroll area.

This is an iOS-only property, and the default is true.

Item	Contents
Type	boolean
Default	true
Platform	iOS

Enable pull-to-refresh (pullToRefreshEnabled)

sets whether to enable the pull-to-refresh behavior that refreshes when pulled down.

This is an iOS-only option, and the default is trueis. If you set this value to trueto bounces the option also automatically trueis set to.

Item	Contents
Type	boolean
Default	true
Platform	iOS

Configure over-scroll behavior (overScrollMode)

sets how Android handles the over-scroll effect when reaching the end of scrollable content.

Item	Contents
Type	'always' | 'content' | 'never'
Default	'always'
Platform	Android

The meaning of each value is as follows.

Value	Description
'always'	Allows the over-scroll effect regardless of content size.
'content'	Allows the over-scroll effect only when the content is larger than the WebView.
'never'	Does not use the over-scroll effect.

Note: Android official documentation

Restrict media autoplay (mediaPlaybackRequiresUserAction)

sets whether to prevent audio or video from playing automatically.

If you set this value to truethe media will play only when the user taps it directly. On Android, this option applies only on version 17 or later.

Item	Contents
Type	boolean
Default	true
Platform	iOS, Android

Note: react-native-webview mediaPlaybackRequiresUserAction

Allow swipe back/forward navigation (allowsBackForwardNavigationGestures)

sets whether to allow back or forward navigation using left/right swipe gestures.

If you set this value to falseIf set to this value, users cannot navigate between pages with swipe gestures.

Item	Contents
Type	boolean
Default	true
Platform	iOS

Note: react-native-webview allowsBackForwardNavigationGestures

Configuration example

The example below configures WebView scroll behavior and media playback behavior together.

import { defineConfig } from '@apps-in-toss/web-framework/config';

export default defineConfig({
  webView: {
    bounces: true,
    pullToRefreshEnabled: true,
    allowsInlineMediaPlayback: false,
    overScrollMode: 'never',
  },
});

Notes

• Some WebView properties are iOS- or Android-only. Be sure to check the differences in behavior by platform.
• We recommend carefully configuring options that have a major impact on the user experience to match your service.
• WebView properties are applied at configuration time, not at runtime.