Skip to main content
Version: Current

App Actions

os.compileApp(appId: string, content: any): SetAppOutputAction

Compiles the app with the given ID to display the given content. Each time this function is called, the app will be cleared and will display the specified content.

Used in tandem with os.registerApp(portalId, bot) to create custom apps.

The first parameter is a string and is the ID of the app.

The second parameter is a any and


Display a header
os.compileApp('myApp', <h1>Hello World!</h1>);
Display a button
<button onClick={ () => os.toast("You clicked the button!")}>
Click Me!
Display an input box
<input onInput={ (e) => { tags.label = } } />
Display a slider input
<input type="range" min="0" max="100" onInput={ (e) => { tags.label = } } />

os.listBuiltinTags(): string[]

Gets the list of tag names that are built-in to CasualOS.

Includes tags like #color and #gridPortal, but not user-defined ones like {@tag [dimension]}.


Get the list of built-in tags
const builtinTags = os.listBuiltinTags();

os.registerApp(portalId: string, bot: (string | Bot)): Promise<void>

Registers a app with the given ID, bot, and options. Returns a promise that resolves when the app has been registered. Can be called multiple times with new options to override previous options.

Once setup, CasualOS will send a @onAppSetup whisper to the given bot. At this point, you can call os.compileApp(appId, content) to set what the app displays.

CasualOS will also define a global variable {app}Bot that points to the given bot.

Apps work by running the HTML you give it by calling os.compileApp(appId, content) with the HTML you want the app to show. Since JavaScript does not natively support HTML, we are using a special extension called JSX that adds HTML-like syntax to JavaScript.

At the most basic, JSX is like writing HTML inside JavaScript:

let htmlData = <div>
    <h1>Hello World</h1>

See this article for more information: Introducing JSX

CasualOS also includes a helper called html that can be used to make HTML objects out of a string. You can use it to convert a string into HTML by adding it before a string that uses backticks, like this:

let htmlData = html`
        <h1>Hello World</h1>

JSX is the preferred way to write HTML inside JavaScript since CasualOS can properly detect it and add helpful features like syntax highlighting and error messages.

The first parameter is a string and is the ID that the app should have.

The second parameter is a (string | Bot) and is the bot that should represent the app. This is the bot that recieves the @onAppSetup whisper and should generally be in charge of calling os.compileApp(appId, content) .


Setup a basic app
await os.registerApp('basicApp', thisBot);
os.compileApp('basicApp', <h1>Hello World!</h1>);
Setup an app with a button
await os.registerApp('buttonApp', thisBot);

<button onClick={ () => os.toast("You clicked the button!") }>
Click Me!
Setup an app with an input box
await os.registerApp('inputApp', thisBot);

<input onInput={ (e) => { tags.label = } }>

os.registerTagPrefix(prefix: string, options?: RegisterPrefixOptions): Promise<void>

Specifies that the given prefix should be used to indicate that the tag contains script content. Use this function to specify custom prefixes that function similarly to @ or 🧬.

The first parameter is a string and is the prefix that should indicate that the rest of the tag value is a script.

The second parameter is optional and is a RegisterPrefixOptions and is the options that should be used for the prefix.


Add 📖 as an script prefix.
await os.registerTagPrefix("📖");
Register some arbitrary text as a prefix.
await os.registerTagPrefix("myPrefix");
Register a prefix as JSX code.
await os.registerTagPrefix("🔺", {
language: "jsx"
Register a prefix with a name.
await os.registerTagPrefix("🔺", {
language: "jsx"
name: 'Triangle'

os.unregisterApp(appId: string): Promise<void>

Unregisters and removes the app with the given ID. Returns a promise that resolves when the app has been removed.

The first parameter is a string and is the ID of the app.


Unregister an app
await os.unregisterApp('myApp');