> For the complete documentation index, see [llms.txt](https://developers-apps-in-toss.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-en/common/navigationbar.md).

# Navigation bar settings

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

{% hint style="info" %}
**Note**

For mini app logo settings, please refer to the WebView settings or React Native settings documentation.
{% endhint %}

***

### 1. Navigation bar basic features

#### Game

The game navigation bar is **More button**and **Close (X) button**is composed of. `granite.config.ts`Set the app type `game`to use the game navigation bar.

{% tabs %}
{% tab title="WebView" %}

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

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

{% endtab %}

{% tab title="React Native" %}

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

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

{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Note**

* [safeArea](/documentation/api-and-sdk-en/common/screen/safe-area.md) Please refer to the documentation and develop so that the X button does not overlap with other buttons on the game screen.
  {% endhint %}

#### Non-game

In non-game mini apps, a navigation bar with a white background is provided by default. On the left is **the mini app logo**and **Name**and on the right are **More button**and **the X button**located.

#### More button features

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

**Contact us / Report**

registered in the console **customer center link and website address**are displayed automatically. Through the report feature, users can send reports, and partners can check the report details through the console.

**Share**

Users can easily share the mini app with others. When sharing, **mini app name**and **deep link address**are sent together.

**Permission settings**

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

**Add to home screen**

You can register frequently used mini apps directly on the phone's home screen. Available starting with Toss app 5.246.0 or later.

**Delete mini app storage**

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

**Mini app notifications ON/OFF**

You can directly set whether to receive notifications for each mini app. You can turn service-specific notifications ON/OFF through the settings button on the mini app navigation bar.

***

### 2. Navigation bar customization

`granite.config.ts`the `navigationBar` You can set how the navigation bar is displayed using options.

```typescript
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`** — Sets whether to display a back button on the left side of the navigation bar.
* **`withHomeButton`** — Sets whether to display a button that navigates to the home screen in non-game mini apps.
* **`withTitle`** — Sets whether to display the mini app icon and mini app name on the left side of the navigation bar.
* **`transparentBackground`** — Determines whether the navigation bar background is transparent. Suitable for full-screen layouts where content continues underneath the navigation bar.
* **`theme`** — Sets the navigation bar theme to `light` or `dark`. Used when adjusting button and text colors to match the background color.
* **`initialAccessoryButton`** — Initially displays an accessory icon in the left area of the More button. Only one can be displayed 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 set it up like below.

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

If you want to initially display the home button and accessory icon, set it up like below.

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

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

{% tabs %}
{% tab title="WebView" %}

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

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

{% endtab %}

{% tab title="React Native" %}

```typescript
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,
      },
    }),
  ],
});
```

{% endtab %}
{% endtabs %}

***

### 3. Design guide

The top navigation uses **monotone icons**only. This is because color icons can overly distract visual attention and cause confusion through unnecessary emphasis. Except for special cases, everything is unified with **monotone icons**and used.

***

### 4. Add accessory icon

In the top right of both game and non-game mini apps **left area of the More button**you can add one icon.

#### Platform-specific setup method

* **WebView**
  * `partner.addAccessoryButton()`to add a button at runtime.
  * Click events are received with `tdsEvent.addEventListener('navigationAccessoryEvent')`.
  * For initial display, use `defineConfig`the `navigationBar.initialAccessoryButton` option.
* **React Native**
  * `useTopNavigation()`the `addAccessoryButton()`to add a button at runtime.
  * or `granite.config.ts`the `navigationBar.initialAccessoryButton`can be used to display the button in the initial state.

```typescript
interface NavigationBarOptions {
  withBackButton?: boolean; // Whether to show the back button
  withHomeButton?: boolean; // Whether to show the home button
  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

{% tabs %}
{% tab title="Web" %}

```tsx
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',
      },
    },
  },
});
```

{% endtab %}

{% tab title="React Native" %}

```tsx
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',
        },
      },
    }),
  ],
});
```

{% endtab %}
{% endtabs %}

#### Dynamic addition

{% tabs %}
{% tab title="Web (JS)" %}

```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();
});
```

{% endtab %}

{% tab title="Web (React)" %}

```tsx
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;
}, []);
```

{% endtab %}

{% tab title="React Native" %}

```tsx
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();
  };
}, []);
```

{% endtab %}
{% endtabs %}

***

### 5. Add home button

In non-game mini apps, you can display a **button that navigates to the home screen**on the top left. The home button is located to the right of the service name and helps users return to the first screen at any time. Control of home button behavior is [controlling events](/documentation/api-and-sdk-en/common/screen/event.md) please refer to the document.

{% hint style="info" %}
**Please note**

* Do not add a home button again in the right accessory button area.
* The home button only serves as a "service entry point," and custom functions or additional text are not possible.
  {% endhint %}

```typescript
interface NavigationBarOptions {
  withHomeButton?: boolean; // Whether to display the home button
}
```

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

***

### Notes

* Accessory buttons are **monotone icons**supported only.
* Only one accessory button can be displayed at a time.
* Color icons or adding custom UI are not supported.
* The home button can only be used in non-game mini apps.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-en/common/navigationbar.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.