Skip to content

Schema reference

An exhaustive reference for the Toolpad Studio file formats.

Files

These are the various files supported by toolpad.

Application

object
Defines the version of this object. Used in determining compatibility between Toolpad Studio "application" objects.
apiVersion: "v1"
Describes the nature of this Toolpad Studio "application" object.
kind: "application"
Defines the shape of this "application" object
spec: object
The plan for this application.
plan: "free" | "pro"
Authentication configuration for this application.
authentication: object
Authentication providers to use.
providers: array of object
Unique identifier for this authentication provider.
provider: "github" | "google" | "azure-ad" | "credentials"
Role mapping definition for this authentication provider.
roles: array of object
Authentication provider roles to be mapped from.
source: array of string
Toolpad Studio role to be mapped to.
target: string
Valid email patterns for the authenticated user.
restrictedDomains: array of string
Authorization configuration for this application.
authorization: object
Available roles for this application. These can be assigned to users.
roles: array of any of
  • string
  • object
    The name of the role.
    name: string
    A description of the role.
    description: string

Page

object
Defines the version of this object. Used in determining compatibility between Toolpad Studio "page" objects.
apiVersion: "v1"
Describes the nature of this Toolpad Studio "page" object.
kind: "page"
Defines the shape of this "page" object
spec: object
Page name to display in the UI.
displayName: string
Serves as a canonical id of the page. Deprecated: use an alias instead.
id: string
Page name aliases.
alias: array of 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
Parameters to pass to this query.
parameters: array of
A name/value pair.
object
The name
name: string
The value
value: any of
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
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
Authorization configuration for this page.
authorization: object
Allow all users to access this page.
allowAll: boolean
Roles that are allowed to access this page.
allowedRoles: array of 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 Studio chrome and just display the content of the page
    "standalone"
  • Show Toolpad Studio header and navigation.
    "shell"
Top level element of the page.
maxWidth: "xs" | "sm" | "md" | "lg" | "xl" | "none"

Theme

object
Defines the version of this object. Used in determining compatibility between Toolpad Studio "theme" objects.
apiVersion: "v1"
Describes the nature of this Toolpad Studio "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 Studio 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

BindableProp

any of

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 height this element takes up, in pixels.
height: 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 Studio 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

SimplePaletteColorOptions

object
main: string
light: string
dark: string
contrastText: string