Create Pages
Include pages in your Kizen app to display full-screen content with optional links in the global navigation.
Overview
Pages are complete, full-screen web pages that appear within Kizen (see Figure 1). They have unique URLs that work for anyone who installs your app. Depending on how you configure your pages, you can automatically create toolbar items for them that the user can add to their global navigation.

The content of a page can come from custom HTML, or you can embed the content from a page on the web.
Add a page to your app
Add your pages to the pages directory in src. Place each page in its own subdirectory with config.json, script.js, styles.css , and callback.js files as needed, like this:
The following table describes these files:
config.json
JSON
The configuration file for the page.
Yes
script.js
JavaScript
The script that runs when the page opens.
Yes
styles.css
Cascading Style Sheet
The styles for the content on the page. If the page embeds content from an outside source, you don't need this file.
No
callback.js
JavaScript
The script that runs when the page receives a cross-document message of the kizen:plugin_callback type. If your page doesn't listen for these messages, you don't need this file.
No
Pages also support event scripts. Place event scripts in the page's eventScripts subdirectory. For more information about event scripts, see the coding reference.
See below for details on each of these files.
About config.json for pages
The configuration file for a page sets the properties of the page:
The keys are as follows:
api_name
The API name of the page 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 page's subdirectory.
Yes
name
The name of the page.
No
is_toolbar_item
Whether the page adds a toolbar item to the global navigation. When this value is true, the name field supplies the label of the page's toolbar item.
No
toolbar_color
The color of the page's toolbar label and icon when the toolbar item is active. Set the value to a hexadecimal color code, CSS color, or color keyword. When is_toolbar_item is false, the value of this key has no effect.
No
toolbar_icon
The name of the icon that appears next to the label in the global navigation. For the available icons, see the coding reference. When is_toolbar_item is false, the value of this key has no effect.
No
About script.js for pages
The JavaScript file for a page is the page's main script. Kizen runs the script once, when the page opens. The script sets the starting state of the page.
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 the user can do in Kizen, with the same permissions, and it knows their name and currently active business. However:
A page script has no DOM access. It can show toasts and modals and navigate to other pages, but it can't otherwise change the browser window outside the page.
A page script runs only while the page is open. Navigating to another page or closing Kizen entirely stops the script. For tasks that need to run on their own, use an agentic workflow code step instead.
A page script starts fresh each time the page opens, including when the user refreshes it or returns to it. To carry values from previous runs, attach them as query parameters to the page's URL. See Pass values to the page below for details.
A page script must finish before the user can interact with the page. Code that runs on a loop or long delay, like a status message that refreshes every minute, belongs in an event script.
Paint content into the page
To paint content into the page, use one of two methods. Use this.outputUI() for HTML and CSS:
The method takes a single HTML string as its argument. The CSS comes from the page's styles.css file or from inline style attributes in the HTML. For security, Kizen strips out <script> tags, event handlers, and javascript: links but leaves SVG, images, and <iframe> elements. For more information, see the coding reference.
To embed a live web page, use this.outputIframe():
The page loads from its own server and runs its own code, so it can update itself. The address must start with https://, and the site must allow embedding. For more information, see the coding reference.
Pass values to the page
To pass values to the page, attach them to the page's URL as query parameters:
When the page opens, Kizen turns your query parameters into properties of the page's this.args object. In the example above, the script receives this.args.seed and this.args.status with their respective values.
When working with the this.args object:
All values are strings, even numeric values. Use the
Number()JavaScript function to convert a numeric string to a number.Missing query parameters are undefined. If your script depends on a
this.argsproperty to have a value, use the logical OR operator to specify a default, like this:
The page's event scripts can access the same
this.argsproperties as the page itself. However, the page'scallback.jsscript can't. It receives only the values from the callback.
For more information about this.args, see the coding reference.
About styles.css for pages
The style sheet for a page provides the style definitions for the classes in the page's custom HTML:
You don't need a style sheet if your page uses this.outputIframe() to embed a live web page.
About callback.js for pages
The callback.js file for a page is a script that runs when Kizen's browser window receives a callback, which is a cross-document message of the kizen:plugin_callback type, while the page is open. The callback arrives when the user completes a task in the embedded page of an external service, like signing an agreement or making a payment. Depending on the service, it can also arrive if the user cancels the task without completing it. The service redirects the user to the /plugins/callback address at Kizen, which is what sends the callback message that the page receives along with an optional query string.
The callback script contains logic for what happens on the page in response to the user's action:
The script receives values through properties of the this.args object, which it gets from the optional query parameters of the /plugins/callback URL:
Add a page's toolbar item to the global navigation
When a user installs your app, the toolbar items for the app's pages don't automatically appear in their global navigation. The user must manually add them to their toolbar layout.
To add a page's toolbar item to the global navigation:
Add the toolbar item to the global navigation
To add the toolbar item to the global navigation:
In the Available Options list, find the toolbar item to add (see Figure 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).

When you're satisfied with the placement, select Save.
After you add toolbar items from an app 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.
What's next?
Continue to Create Blocks to learn how to include blocks in your app.
Last updated
Was this helpful?