Navigation bar settings

The navigation bar is a common UI component fixed at the top of the screen. When you apply the Apps in Toss SDK, the navigation bar is displayed automatically without any separate implementation.

See the reference

For mini-app logo settings, please refer to the WebView settings or React Native settings documentation.

---

1. Basic navigation bar features

Game

The navigation bar for games More buttonand Close (X) buttonconsists of. granite.config.tsIn gameif you set the app type to game, you can use the game navigation bar.

WebView

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

export default defineConfig({
  // ...
  webViewProps: {
    type: 'game',
  },
});

React Native

import { appsInToss } from '@apps-in-toss/framework/plugins';
import { defineConfig } from '@granite-js/react-native/config';

export default defineConfig({
  // ...
  plugins: [
    appsInToss({
      // ...
      appType: 'game',
    }),
  ],
});

See the reference

• safeArea Please develop according to the documentation so that the X button does not overlap with other buttons on the game screen.

Non-game

In non-game mini-apps, a navigation bar with a white background is provided by default. On the left are mini-app logoand nameand, on the right, More buttonand X buttonare located.

More button features

Through the More button, you can use the following features right away without separate server integration or additional implementation.

Contact / Report

registered in the console customer support link and website addressare automatically displayed. Through the report feature, users can submit reports, and partners can review the report details in the console.

Share

Users can easily share the mini-app with others. When sharing, mini-app nameand deep link addressare sent together.

Permission settings

Users can check the permissions requested by the mini-app and control them with ON/OFF at any time.

Add to Home Screen

You can add frequently used mini-apps directly to your phone's home screen. This is available from Toss app 5.246.0 and later.

Delete mini-app storage

You can selectively delete the storage of mini-apps you don't use often. Through the settings button in the mini-app navigation bar, you can delete service-specific data.

Mini-app notifications ON/OFF

You can directly set whether to receive notifications for each mini-app. Through the settings button in the mini-app navigation bar, you can turn service notifications ON/OFF.

---

2. Customizing the navigation bar

granite.config.tsof navigationBar You can configure how the navigation bar is displayed with the options.

interface NavigationBarOptions {
  withBackButton?: boolean;
  withHomeButton?: boolean;
  withTitle?: boolean;
  transparentBackground?: boolean;
  theme?: 'light' | 'dark';
  initialAccessoryButton?: InitialAccessoryButton;
}

interface InitialAccessoryButton {
  id: string;
  title?: string;
  icon: {
    name: string;
  };
}

• withBackButton — Set whether to show the back button on the left side of the navigation bar.
• withHomeButton — Set whether to show the button that moves to Home in non-game mini-apps.
• withTitle — Set whether to display the mini-app icon and mini-app name on the left side of the navigation bar.
• transparentBackground — Determine whether to make the navigation bar background transparent. This is suitable for full-screen layouts where content continues beneath the navigation bar.
• theme — Set the navigation bar theme to light or dark. Use this when adjusting button and text colors to match the background color.
• initialAccessoryButton — Initially show an accessory icon in the left area of the More button. Only one can be shown at a time.

For example, if you want to hide the mini-app icon and app name and place the navigation bar over a dark background, you can configure it like this.

navigationBar: {
  theme: 'dark',
  transparentBackground: true,
  withTitle: false,
}

To initially show the Home button and accessory icon, configure it like this.

navigationBar: {
  withBackButton: true,
  withHomeButton: true,
  initialAccessoryButton: {
    id: 'heart',
    title: 'Heart',
    icon: {
      name: 'icon-heart-mono',
    },
  },
}

If it's a game app, transparentBackground set true please.

WebView

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

export default defineConfig({
  // ...
  navigationBar: {
    transparentBackground: true,
  },
});

React Native

import { appsInToss } from '@apps-in-toss/framework/plugins';
import { defineConfig } from '@granite-js/react-native/config';

export default defineConfig({
  // ...
  plugins: [
    appsInToss({
      // ...
      navigationBar: {
        transparentBackground: true,
      },
    }),
  ],
});

If you want to increase screen immersion like a game even in a non-game app, you can configure a navigation bar with a transparent background that leaves only the More button and Close button.

WebView

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

export default defineConfig({
  // ...
  navigationBar: {
    withBackButton: false,
    withHomeButton: false,
    withTitle: false,
    transparentBackground: true,
  },
});

React Native

import { appsInToss } from '@apps-in-toss/framework/plugins';
import { defineConfig } from '@granite-js/react-native/config';

export default defineConfig({
  // ...
  plugins: [
    appsInToss({
      // ...
      navigationBar: {
        withBackButton: false,
        withHomeButton: false,
        withTitle: false,
        transparentBackground: true,
      },
    }),
  ],
});

---

3. Design guide

To deliver a consistent information structure to users, the top navigation monotone iconsonly uses. This is because color icons can excessively distract visual attention and cause confusion through unnecessary emphasis. Except for special cases, everything is unified with monotone iconsand used that way.

---

4. Adding an accessory icon

Both game and non-game mini-apps, in the upper right left area of the More buttoncan add one icon.

Platform-specific configuration methods

• WebView

  • partner.addAccessoryButton()can be used to add a button at runtime.
  • Click events are handled via tdsEvent.addEventListener('navigationAccessoryEvent').
  • Initial display uses defineConfigof navigationBar.initialAccessoryButton option.
• React Native

  • useTopNavigation()of addAccessoryButton()can be used to add a button at runtime.
  • or granite.config.tsof navigationBar.initialAccessoryButtoncan be used to show the button in the initial state.

interface NavigationBarOptions {
  withBackButton?: boolean; // whether the back button exists
  withHomeButton?: boolean; // whether the Home button exists
  withTitle?: boolean; // whether to display the mini-app icon and app name
  transparentBackground?: boolean; // whether the background is transparent
  theme?: 'light' | 'dark'; // navigation bar theme
  initialAccessoryButton?: InitialAccessoryButton; // only one can be displayed
}

interface InitialAccessoryButton {
  id: string;
  title?: string;
  icon: {
    name: string;
  };
}

Initial settings

Web

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

export default defineConfig({
  // ...
  navigationBar: {
    withBackButton: true,
    withHomeButton: true,
    initialAccessoryButton: {
      id: 'heart',
      title: 'Heart',
      icon: {
        name: 'icon-heart-mono',
      },
    },
  },
});

React Native

import { appsInToss } from '@apps-in-toss/framework/plugins';
import { defineConfig } from '@granite-js/react-native/config';

export default defineConfig({
  // ...
  plugins: [
    appsInToss({
      // ...
      navigationBar: {
        withBackButton: true,
        withHomeButton: true,
        initialAccessoryButton: {
          icon: {
            name: 'icon-heart-mono',
          },
          id: 'heart',
          title: 'Heart',
        },
      },
    }),
  ],
});

Dynamic addition

Web (JS)

import { partner, tdsEvent } from '@apps-in-toss/web-framework';

partner.addAccessoryButton({
  id: 'heart',
  title: 'Heart',
  icon: {
    name: 'icon-heart-mono',
  },
});

const cleanup = tdsEvent.addEventListener('navigationAccessoryEvent', {
  onEvent: ({ id }) => {
    if (id === 'heart') {
      console.log('Button clicked');
    }
  },
});

window.addEventListener('pagehide', () => {
  cleanup();
});

Web (React)

import { partner, tdsEvent } from '@apps-in-toss/web-framework';

useEffect(() => {
  partner.addAccessoryButton({
    id: 'heart',
    title: 'Heart',
    icon: {
      name: 'icon-heart-mono',
    },
  });

  const cleanup = tdsEvent.addEventListener('navigationAccessoryEvent', {
    onEvent: ({ id }) => {
      if (id === 'heart') {
        console.log('Button clicked');
      }
    },
  });

  return cleanup;
}, []);

React Native

import { useTopNavigation } from '@apps-in-toss/framework';
import { tdsEvent } from '@toss/tds-react-native';

const { addAccessoryButton } = useTopNavigation();

addAccessoryButton({
  id: 'heart',
  title: 'Heart',
  icon: {
    name: 'icon-heart-mono',
  },
  onPress: () => console.log('Button clicked'),
});

useEffect(() => {
  const cleanup = tdsEvent.addEventListener('navigationAccessoryEvent', {
    onEvent: ({ id }) => {
      if (id === 'heart') {
        console.log('heart clicked');
      }
    },
  });

  return () => {
    cleanup();
  };
}, []);

---

5. Adding a Home button

In non-game mini-apps, in the upper left a button that moves to Homecan be displayed. The Home button is placed to the right of the service name and helps users return to the first screen at any time. For controlling Home button behavior, Controlling events please refer to the documentation.

Please note

• Please do not add the Home button redundantly in the right accessory button area.
• The Home button only serves as a "service entry point," and custom functions or additional text cannot be added.

interface NavigationBarOptions {
  withHomeButton?: boolean; // whether to display the Home button
}

navigationBar: {
  withBackButton: true,
  withHomeButton: true,
}

---

Notes

• Accessory buttons are monotone iconssupported only.
• Only one accessory button can be displayed at a time.
• Color icons or custom UI additions are not supported.
• The Home button is only available in non-game mini-apps.