UI Parts

UI Parts are the building blocks for creating user interfaces in your scripts. The provide a way to display information and get user input. UI Parts can be used in various UI Extensions such as Sidebar Panels, Script Panels, and Toolbox Options as well as in Modals and Windows.

All UI Parts are defined as objects with a type property that specifies the kind of UI Part it is. Each type has its own set of properties that define its behavior and appearance.

Layout Components

Row

A row layout arranges its child components horizontally in a single line. It accepts a content property which is an array of UI Parts to be displayed in the row. It functions as a flex container with row direction and has spacing and alignment properties to control the spacing between items and their vertical alignment.

Example:

{
  type: 'row',
  content: [
    {
      type: 'text',
      text: 'First Item'
    },
    {      
      type: 'text',
      text: 'Second Item'
    }
  ]
}

Column

A column layout arranges its child components vertically in a single column. It accepts a content property which is an array of UI Parts to be displayed in the column. It functions as a flex container with column direction and has spacing and alignment properties to control the spacing between items and their horizontal alignment.

Example:

{
  type: 'column',
  content: [
    {
      type: 'text',
      text: 'First Item'
    },
    {
      type: 'text',
      text: 'Second Item'
    }
  ]
}

Box

A box layout places its child components in a bordered box with a background color. It accepts a content property which is an array of UI Parts to be displayed inside the box. If you want a custom-styled box, use a Container with the style property instead.

Example:

{
  type: 'box',
  content: [
    {
      type: 'text',
      text: 'This is inside a box.'
    }
  ]
}

Container

A container is a simple wrapper that wraps its child components in a plain div. It accepts a content property which is an array of UI Parts to be displayed inside the container. Containers are useful for applying custom styles to a group of UI Parts using the style property.

Example:

{
  type: 'container',
  style: {
    border: '1px solid #ff0000',
    padding: '10px'
  },
  content: [
    {
      type: 'text',
      text: 'This is inside a custom-styled container.'
    }
  ]
}

Input Components

Text Input

A single-line text input allows users to enter and edit text. It has a storageKey property that can be used to bind the input value to persistent storage, enabling the value to be saved and retrieved across sessions. onChange and onSubmit callbacks can also be provided to respond to user input in real-time or when the user submits the input (e.g., by pressing Enter).

Example:

{
  type: 'textInput',
  storageKey: 'user-value',
  onChange: (value) => {
    api.v1.log('User changed input to: ' + value)
  },
  onSubmit: (value) => {
    api.v1.log('User submitted input: ' + value)
  }
}

Multiline Text Input

A multiline text input allows users to enter and edit larger blocks of text. It has a storageKey property that can be used to bind the input value to persistent storage, enabling the value to be saved and retrieved across sessions. onChange and onSubmit callbacks can also be provided to respond to user input in real-time or when the user submits the input (e.g., by pressing Ctrl+Enter).

Example:

{
  type: 'multilineTextInput',
  storageKey: 'user-multiline-value',
  onChange: (value) => {
    api.v1.log('User changed multiline input to: ' + value)
  },
  onSubmit: (value) => {
    api.v1.log('User submitted multiline input: ' + value)
  }
}

Number Input

A number input allows users to enter and edit numeric values. It has a storageKey property that can be used to bind the input value to persistent storage, enabling the value to be saved and retrieved across sessions. onChange and onSubmit callbacks can also be provided to respond to user input in real-time or when the user submits the input (e.g., by pressing Enter).

Example:

{
  type: 'numberInput',
  storageKey: 'user-number-value',
  onChange: (value) => {
    api.v1.log('User changed number input to: ' + value)
  },
  onSubmit: (value) => {
    api.v1.log('User submitted number input: ' + value)
  }
}

Checkbox Input

A checkbox input allows users to toggle a boolean value. It has a storageKey property that can be used to bind the input value to persistent storage, enabling the value to be saved and retrieved across sessions. An onChange callback can also be provided to respond to user input in real-time.

Example:

{
  type: 'checkboxInput',
  storageKey: 'user-checkbox-value',
  onChange: (value) => {
    api.v1.log('User changed checkbox to: ' + value)
  }
}

Display Components

Text

A text display component shows a piece of text. It has a text property for the content to display. The markdown property can be set to true to enable markdown formatting in the text. URLs do not become clickable links for security and privacy reasons.

Text contained within {{curly braces}} will be treated as a storage key and replaced with the corresponding stored value. If you want to disable this behaviour, you can set noTemplate to true. To use this with historyStorage, storyStorage, or tempStorage, use the syntax {{history:key}}, {{story:key}}, or {{temp:key}}.

Example:

{
  type: 'text',
  text: `# Heading
This is **bold** text and this is *italic* text.`,
  markdown: true
}

Image

An image display component shows an image. It has a src property for the image URL. The alt property can be used to provide alternative text for the image.

The src property only supports Data URLs (e.g., “data:image/png;base64,…”) and you cannot load images from external URLs for security and privacy reasons.

For various reasons, it’s recommended to also set explicit height and width properties to control the size of the image.

Example:

{
  type: 'image',
  src: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...',
  alt: 'Example Image'
  height: 200,
  width: 200
}

Button

A button component displays a clickable button. It has a text property for the button label and a callback property which is a function that will be called when the button is clicked. The button can be disabled by setting the disabled property to true or can be disabled while its callback is running by setting disableWhileCallbackRunning to true.

Example:

{
  type: 'button',
  text: 'Click Me',
  callback: () => {
    api.v1.log('Button was clicked!')
  }
}

Styling

Most UI Parts can use the style property to customize their appearance. This property accepts an object with CSS properties and values. Properties should be written in camelCase format (e.g., backgroundColor instead of background-color).

This sets inline styles, so you cannot use pseudo-classes or media queries. URLs are stripped from style properties for security and privacy reasons.

If you use the key of a theme color (e.g., bg0, textHeading, warning) or font family (e.g., default, headings) as a value it will be replaced with the actual value from the current theme.

State Management

Storage Keys

Many input UI Parts support a storageKey property which can be used to bind the input value to persistent storage. When a user changes the value of the input, it will automatically be saved to storage under the specified key. If the value in storage changes (e.g., from another UI Part or script), the input will automatically update to reflect the new value.