Skip to content

Schema reference

An exhaustive reference for the Toolpad file formats.

Files

These are the various files supported by toolpad.

Page

object

Defines the version of this object. Used in determining compatibility between Toolpad "page" objects.

apiVersion: "v1"

Describes the nature of this Toolpad "page" object.

kind: "page"

Defines the shape of this "page" object

spec: object

Serves as a canonical id of the page.

id: string

Title for this page.

title: string

Parameters for the page. These can be set inside of the url query string.

parameters: array of NameStringValuePair

Queries that are used by the page. These will load data when the page opens.

queries: array of object

A name for the query

name: string

Activates or deactivates the query. When deactivated the data won't be loaded when the page opens.

enabled: any of

boolean
JsExpressionBinding
EnvBinding

Parameters to pass to this query.

parameters: array of

A name/value pair.

object

The name

name: string

The value

value: any of

any
JsExpressionBinding
EnvBinding

How to fetch this query.

mode: any of

Fetch automatically when the page opens
"query"
Fetch on manual action only
"mutation"

Query definition

query: any of

object
Designates this object as a fetch query.
kind: "rest"
The URL of the request
url: any of
string
JsExpressionBinding
EnvBinding
The request method.
method: string
Extra request headers.
headers: array of BindableNameStringValue
Extra url query parameters.
searchParams: array of BindableNameStringValue
The request body.
body: any of
object
kind: "raw"
content: any of
string
JsExpressionBinding
EnvBinding
contentType: string
object
kind: "urlEncoded"
content: array of BindableNameStringValue
Run a custom transformer on the response.
transformEnabled: boolean
The custom transformer to run when enabled.
transform: string
How to parse the response.
response: any of
Don't interpret this body at all.
object
kind: "raw"
Interpret the fetch response as JSON
object
kind: "json"
Interpret the fetch response as CSV
object
kind: "csv"
First row contains headers
headers: boolean
Interpret the fetch response as XML
object
kind: "xml"
object
Designates this object as a local function query.
kind: "local"
The function to be executed on the backend by this query.
function: string

Transformation to run on the response

transform: string

Enable the transformation

transformEnabled: boolean

Interval to rerun this query at

refetchInterval: number

Time to cache before refetching

cacheTime: number

The content of the page. This defines the UI.

content: array of Element

The content of the page as JSX. Experimental, do not use!.

unstable_codeFile: string

Display mode of the page. This can also be set at runtime with the toolpad-display query parameter

display: any of

Hide the Toolpad chrome and just display the content of the page
"standalone"
Show Toolpad header and navigation.
"shell"

Theme

object

Defines the version of this object. Used in determining compatibility between Toolpad "theme" objects.

apiVersion: "v1"

Describes the nature of this Toolpad "theme" object.

kind: "theme"

Defines the shape of this "theme" object

spec: object

The ThemeOptions object that gets fed into MUI's createTheme function.

options: object

palette: object

mode: "light" | "dark"

primary: SimplePaletteColorOptions

secondary: SimplePaletteColorOptions

*: any

*: any

Definitions

These are shared definitions used throughout Toolpad files.

JsExpressionBinding

A binding that evaluates an expression and returns the result.

object

The expression to be evaluated.

$$jsExpression: string

EnvBinding

An environment variable.

object

The name of an environment variable.

$$env: string

JsExpressionAction

A javascript expression to be executed when this action is triggered.

object

The code to be executed.

$$jsExpressionAction: string

NavigationAction

A navigation from one page to another, optionally passing parameters to the next page.

object

$$navigationAction: object

The page that is being navigated to

page: string

Parameters to pass when navigating to this page

parameters: object

*: any of

any
JsExpressionBinding
EnvBinding

BindableProp

any of

string
number
boolean
null
array of BindableProp
object
*: BindableProp
JsExpressionBinding
EnvBinding
JsExpressionAction
NavigationAction
Template

Element

The instance of a component. Used to build user interfaces in pages.

object

The component that this element was based on.

component: string

a name for this component, which is used to reference it inside bindings.

name: string

Layout properties for this element.

layout: object

Lays out the element along the horizontal axis.

horizontalAlign: string

Lays out the element along the vertical axis.

verticalAlign: string

The width this element takes up, expressed in terms of columns on the page.

columnSize: number

The children of this element.

children: array of Element

The properties to configure this instance of the component.

props: object

*: BindableProp

Template

Describes a fragment of Toolpad elements, to be used as a template.

object

The subtree, that describes the UI to be rendered by the template.

$$template: array of Element

NameStringValuePair

a name/value pair with a string value.

object

The name

name: string

The value

value: string

BindableNameStringValue

A name/value pair where the value is dynamically bindable to strings.

object

The name

name: string

The value

value: any of

string
JsExpressionBinding
EnvBinding

SimplePaletteColorOptions

object

main: string

light: string

dark: string

contrastText: string