> For the complete documentation index, see [llms.txt](https://developer.kizen.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.kizen.com/docs/apps-and-integrations/plugin-development/develop-apps/create-app-surfaces/toolbar-items.md).

# Create Toolbar Items

Include toolbar items in your Kizen app to link to pages or launch custom scripts.

{% hint style="success" %}
**Audience:** Developers, solution architects

**Purpose:** Explains how to build toolbar items as surfaces in Kizen apps and how to add them to the global navigation in Kizen
{% endhint %}

## Overview

*Toolbar items* appear in Kizen's global navigation (see Figure 1). Selecting a toolbar item launches a script that can navigate to other locations within Kizen or on the web, call the Kizen API, access external services, and more.

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2FkdlXirKYah8ZfXnAutYg%2Fappdev_toolbaritems_globalnav_cropped.png?alt=media&amp;token=b78d7731-ff93-45b6-8d24-5de3c7d7d7c3" alt="The Clock toolbar item from an app appears in Kizen&#x27;s global navigation." width="563"><figcaption><p><strong>Figure 1:</strong> A toolbar item from an an app in Kizen's global navigation.</p></figcaption></figure></div>

{% hint style="info" %}
**Note:** Pages in your app can also add toolbar items, but these are strictly for navigation. For more information, see [Pages](https://developer.kizen.com/docs/apps-and-integrations/plugin-development/develop-apps/create-app-surfaces/embedded-pages.md).&#x20;
{% endhint %}

***

## Add a toolbar item to your app

Add your toolbar items to the `toolbarItems` directory in `src`. Place each toolbar item in its own subdirectory with `config.json` and `script.js` files, like this:

```
src/
└── toolbarItems/
    ├── clock/
    │   ├── config.json
    │   └── script.js
    └── recordFinder/
        ├── config.json
        └── script.js
```

The following table describes these files:

| File          | Type       | Purpose                                                     | Required? |
| ------------- | ---------- | ----------------------------------------------------------- | --------- |
| `config.json` | JSON       | The configuration file for the toolbar item                 | Yes       |
| `script.js`   | JavaScript | The script that runs when the user selects the toolbar item | Yes       |

For more information about the files, keep reading.

### About `config.json` for toolbar items

The configuration file for a toolbar item sets the properties of the toolbar item:

```json
{
  "api_name": "clock_item",
  "label": "Clock",
  "icon": "calendar-days",
  "color": "#0000ff",
  "when": "!{{userConfig.hideClock}}";
}
```

The keys are as follows:

| Key            | Description                                                                                                                                                                                        | Required? |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| **`api_name`** | The API name of the toolbar item in all lowercase letters. If you don't specify a value for this key, the system automatically generates one based on the name of the toolbar item's subdirectory. | No        |
| **`label`**    | The text of the toolbar item.                                                                                                                                                                      | Yes       |
| **`icon`**     | The name of the icon that appears next to the toolbar item's label. For information on the available icons, see the [coding reference](https://kizen.github.io/app-engine/index.html).             | No        |
| **`color`**    | The color of the label and icon when the toolbar item is active. Set the value to a hexadecimal color code, CSS color, or color keyword.                                                           | No        |
| **`when`**     | A condition that determines when to show the toolbar item in the global navigation. For more information, see the [coding reference](https://kizen.github.io/app-engine/index.html).               | No        |

### About `script.js` for toolbar items

The JavaScript file for a toolbar item provides the code that executes when the user selects the item:

```javascript
const date = new Date();

const time = date.toLocaleTimeString(undefined, {
  hour: 'numeric',
  minute: '2-digit',
});

const day = date.toLocaleDateString(undefined, {
  weekday: 'long',
  month: 'long',
  day: 'numeric',
  year: 'numeric',
});

this.showToast(`It's ${time} on ${day}.`);
```

The script can use standard JavaScript, most web APIs available to Web Workers, and Kizen's runtime API. Because the script acts as the signed-in user, it can do whatever that user can do in Kizen, with the same permissions, and it knows their name and currently active business. However:

* **A toolbar item script doesn't know by itself which record the user is viewing.** For record-specific tasks, use a record action instead, or write logic into the script that gets the user's URL and determines from that the current record.
* **A toolbar item script has no DOM access.** It can display toasts and modals, and it can navigate to other pages, but it can't directly edit the content in the browser window.
* **A toolbar item script requires user interaction.** It can't launch itself. For tasks that need to run automatically, use an agentic workflow code step instead.
* **A toolbar item script starts fresh on each run.** To carry values from previous runs, store them in the user's configuration or as short-term session data. For details, see the [coding reference](https://kizen.github.io/app-engine/glossary.html#session-data).

***

## Add an app toolbar item to the global navigation

When a user install your app, the app's toolbar items don't automatically appear in their global navigation. The user must manually add them to their toolbar layout.

To add an app toolbar item to the global navigation:

{% stepper %}
{% step %}

### Open your user profile

In the global navigation, click your avatar, and select **My Profile** from the menu that appears.
{% endstep %}

{% step %}

### Switch to your toolbar settings

Select **My Toolbar**.
{% endstep %}

{% step %}

### Add the toolbar item to the global navigation

To add the toolbar item to the global navigation:

1. In the Available Options list, find the toolbar item to add (see Figure 2).

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2FyzyLLjqFy8x0zlMIDjtA%2Fappdev_toolbaritems_mytoolbar_available.png?alt=media&amp;token=61008b22-198c-421e-b4d2-8bdce5637f8e" alt="A user finds the Clock toolbar item in the list of available options." width="563"><figcaption><p><strong>Figure 2:</strong> An app's toolbar item in the Available Options list.</p></figcaption></figure></div>

2. Drag the item to the Your Toolbar list, and drop it where you want to place it in the global navigation (see Figure 3).

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2F0ej8tdlIrknUv9WFzspx%2Fappdev_toolbaritems_mytoolbar_yourtoolbar.png?alt=media&amp;token=3854bfc7-f200-45b2-a40f-ff70229b8028" alt="The user drags the Clock toolbar item to the Your Toolbar list and positions it among the existing toolbar items." width="563"><figcaption><p><strong>Figure 3:</strong> The app's toolbar item in the Your Toolbar list.</p></figcaption></figure></div>

{% hint style="info" %}
**Note:** Use the mockup of the global navigation under Preview to help you set the order of the toolbar items.
{% endhint %}

3. When you're satisfied with the placement, select **Save**.
   {% endstep %}
   {% endstepper %}

{% hint style="info" %}
**Note:** You can also add an app's toolbar items to a toolbar template. Depending on the template's settings, other users in your business can access it and apply it to their global navigation without dragging and dropping individual toolbar items. For more information, see our [knowledge base](https://kizen748362562368528725.freshdesk.com/a/solutions/articles/154000202833?portalId=154000122462).&#x20;
{% endhint %}

After you add an app's toolbar items to the global navigation, uninstalling the app hides its toolbar items but doesn't remove them entirely. Reinstalling the app causes the toolbar items to reappear as they were. However, if you adjust your toolbar layout and save it while the app is uninstalled, reinstalling the app doesn't restore its toolbar items. You must add them again manually.

{% hint style="info" %}
**Note:** Setting a `when` condition in the configuration file for the toolbar items overrides your toolbar layout. If the `when` condition doesn't apply, the toolbar items don't appear in the global navigation, even after you have added them.
{% endhint %}

***

## What's next?

Continue to [Create Floating Frames](https://developer.kizen.com/docs/apps-and-integrations/plugin-development/develop-apps/create-app-surfaces/floating-frames.md) to learn how to include floating frames in your app.

<details>

<summary>Related Topics</summary>

* [Apps](https://developer.kizen.com/docs/apps-and-integrations/plugin-development.md)
* [Work with Marketplace Apps](https://developer.kizen.com/docs/apps-and-integrations/plugin-development/work-with-marketplace-apps.md)
* [Work with Business Apps](https://developer.kizen.com/docs/apps-and-integrations/plugin-development/work-with-business-apps.md)
* [Develop Apps](https://developer.kizen.com/docs/apps-and-integrations/plugin-development/develop-apps.md)
* [Work with KiCode](https://developer.kizen.com/docs/apps-and-integrations/plugin-development/develop-apps/work-with-kicode.md)
* [Create App Surfaces](https://developer.kizen.com/docs/apps-and-integrations/plugin-development/develop-apps/create-app-surfaces.md)
* [Create Floating Frames](https://developer.kizen.com/docs/apps-and-integrations/plugin-development/develop-apps/create-app-surfaces/floating-frames.md)
* [Create Pages](https://developer.kizen.com/docs/apps-and-integrations/plugin-development/develop-apps/create-app-surfaces/embedded-pages.md)
* [Create Blocks](https://developer.kizen.com/docs/apps-and-integrations/plugin-development/develop-apps/create-app-surfaces/embedded-blocks.md)
* [Create Data Adornments](https://developer.kizen.com/docs/apps-and-integrations/plugin-development/develop-apps/create-app-surfaces/data-adornments.md)

</details>

***


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developer.kizen.com/docs/apps-and-integrations/plugin-development/develop-apps/create-app-surfaces/toolbar-items.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
