Control App UI

Customize the native app chrome: status bar, navigation spinner, screen rotation, and swipe navigation.

Everything set here through initialize() can also be configured for your brand under Initialization settings in the starti.app Manager, and that is the recommended way to set it: it applies to your whole app with no code, and is changed by publishing rather than releasing your website again. Pass options to initialize() only for values that can only be decided at runtime.

The runtime methods below — setStatusBar(), showSpinner(), enableScreenRotation() and the rest — have no Manager equivalent, and are how you change a setting for one screen rather than for the whole app.

Prerequisites

• The starti.app SDK is installed and initialized

Status bar

Configure on initialization

Set status bar options when initializing the SDK:

await startiapp.initialize({
  statusBar: {
    removeSafeArea: false,
    safeAreaBackgroundColor: "#ffffff",
    hideText: false,
    darkContent: true,
  },
});

Change at runtime

Options are merged onto the current configuration, so you can change a single property without resetting the others:

startiapp.App.setStatusBar({
  removeSafeArea: false,
  safeAreaBackgroundColor: "#1a1a2e",
  hideText: false,
  darkContent: false, // light text for dark backgrounds
});

// Update only the content colour
startiapp.App.setStatusBar({ darkContent: true }); // dark icons for light backgrounds

darkContent defaults to "auto", which lets the app choose the content colour from the configured safe area background colour's brightness. It does not inspect the actual pixels or CSS background behind the status bar.

If you set removeSafeArea: true, your web content extends behind the status bar. In that case, set darkContent explicitly to true or false so the status bar stays readable over your page content. Use true for dark icons on light backgrounds, and false for light icons on dark backgrounds.

startiapp.App.setStatusBar({ darkContent: "auto" });

Hide / show

await startiapp.App.hideStatusBar();
await startiapp.App.showStatusBar();

Set safe area background color

await startiapp.App.setSafeAreaBackgroundColor("#ff0000");

Navigation spinner

The spinner shows during page navigation. Configure it globally:

await startiapp.initialize({
  spinner: {
    show: true,
    color: "#3498db",
    afterMilliseconds: 300,
    excludedDomains: ["api.example.com"],
  },
});

Show / hide programmatically

await startiapp.App.showSpinner();
await startiapp.App.hideSpinner();

Screen rotation

// Allow the screen to rotate
await startiapp.App.enableScreenRotation();

// Lock to current orientation
await startiapp.App.disableScreenRotation();

Swipe navigation

Control iOS-style swipe-back and swipe-forward gestures:

// Enable swipe gestures
await startiapp.App.enableSwipeNavigation();

// Disable swipe gestures (useful for maps, carousels, etc.)
await startiapp.App.disableSwipeNavigation();

Set all options at initialization

Combine everything in a single initialize call:

await startiapp.initialize({
  allowZoom: false,
  allowRotation: false,
  allowDrag: true,
  allowScrollBounce: false,
  allowSwipeNavigation: true,
  statusBar: {
    removeSafeArea: false,
    safeAreaBackgroundColor: "#ffffff",
    hideText: false,
    darkContent: true,
  },
  spinner: {
    show: true,
    color: "#000000",
    afterMilliseconds: 200,
    excludedDomains: [],
  },
});

Splash animation

A brand can ship more than one splash animation and name each one in the starti.app Manager. Your page picks which one the app opens with:

// After sign-in: this device opens on the "returning" animation from now on
startiapp.App.setSplashVariant("returning");

// After sign-out: back to the default animation
startiapp.App.setSplashVariant(null);

The choice takes effect from the next launch, not on the splash currently showing — the app builds its splash before your page exists. It is stored on the device and survives launches and app updates, so treat it as "what this installation opens with", not as part of your session state.

Names that the app does not know — an older app version, or a variant the brand has since removed — fall back to the default animation, so it is safe to call while a new animation is still rolling out. Apps older than 4.229.0 ignore the call entirely; ask startiapp.App.supports("splashVariants") if your page needs to know.

Options stack

Push and pop option sets for different views:

// Enter a fullscreen video view
startiapp.App.pushOptions({
  allowRotation: true,
  allowSwipeNavigation: false,
});

// Leave the fullscreen view, restore previous settings
startiapp.App.popOptions();

See also