> 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 at the top of the screen. When you apply the Apps in Toss SDK, the navigation bar is displayed automatically without any separate implementation.
{% hint style="info" %}
**Please note**
For mini app logo settings, please refer to the WebView settings or React Native settings documentation.
{% endhint %}
***
### 1. Basic navigation bar features
#### Game
The navigation bar for games consists of **More button**and **Close (X) button**. `granite.config.ts`, set the app type to `game`and you can 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" %}
**Please note**
* [safeArea](/documentation/api-and-sdk-en/common/screen/safe-area.md) Please refer to the documentation and develop it 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 are the **mini app logo**and **name**, and on the right are the **More button**and **X button**.
#### More button features
Through the More button, you can use the features below right away without separate server integration or additional implementation.
**Contact us / Report**
registered in the console **customer support link and homepage address**are displayed automatically. 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, the **mini app name**and **deep link address**is sent together.
**Permission settings**
Users can check the permissions requested by the mini app and control them at any time with ON/OFF.
**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. You can delete service-specific data through the settings button in 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 in the mini app navigation bar.
***
### 2. Navigation bar customization
`Non-game` In mini apps, you can customize the navigation in various ways as needed.
`granite.config.ts`of `navigationBar` You can configure how the navigation bar is displayed with the option.
```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 show a back button on the left side of the navigation bar.
* **`withHomeButton`** — sets whether to show a button that takes you to the home screen in non-game mini apps.
* **`withTitle`** — sets whether to show 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. This is suitable for full-screen layouts where content continues under the navigation bar.
* **`theme`** — sets the navigation bar theme to `light` or `dark`. Use this when adjusting button and text colors to match the background color.
* **`initialAccessoryButton`** — initially shows 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 configure it like this.
```typescript
navigationBar: {
theme: 'dark',
transparentBackground: true,
withTitle: false,
}
```
If you want to initially show the home button and accessory icon, configure it like this.
```typescript
navigationBar: {
withBackButton: true,
withHomeButton: true,
initialAccessoryButton: {
id: 'heart',
title: 'Heart',
icon: {
name: 'icon-heart-mono',
},
},
}
```
If it is a game app, `transparentBackground` set `true` .
{% tabs %}
{% tab title="WebView" %}
```typescript
import { defineConfig } from '@apps-in-toss/web-framework/config';
export default defineConfig({
// ...
navigationBar: {
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: {
transparentBackground: true,
},
}),
],
});
```
{% endtab %}
{% endtabs %}
If you want to increase immersion even in non-game apps, like games, 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 to deliver a consistent information structure to users. This is because color icons can distract visual attention too much and cause confusion through unnecessary emphasis. Except for special cases, we use only **unified with monotone icons**.
***
### 4. Adding accessory icons
Both game and non-game mini apps can add one icon to the top-right **left area of the More button**.
#### 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`of `navigationBar.initialAccessoryButton` option.
* **React Native**
* `useTopNavigation()`of `addAccessoryButton()`to add a button at runtime.
* or `granite.config.ts`of `navigationBar.initialAccessoryButton`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 show 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 the home button
In non-game mini apps, you can display **a button that takes you to the home screen**in the top-left corner. The home button is located to the right of the service name and helps users return to the first screen at any time. For control over home button behavior, please refer to [the event control](/documentation/api-and-sdk-en/common/screen/event.md) documentation.
{% hint style="info" %}
**Please note**
* Please do not add a home button redundantly in the right accessory button area.
* The home button only serves as a "service entry point," and custom functions or text cannot be added.
{% endhint %}
```typescript
interface NavigationBarOptions {
withHomeButton?: boolean; // whether to show the home button
}
```
```tsx
navigationBar: {
withBackButton: true,
withHomeButton: true,
}
```
***
### Notes
* Accessory buttons only support **monotone icons**.
* Only one accessory button can be shown at a time.
* Color icons and custom UI additions 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=&goal=
```
`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.
.png?alt=media&token=a17947b5-2688-4c79-8d9f-a6e7321d63e8)