dash.props

Read the settings of a placed pane. You declare props in the pane’s manifest and give them values on the canvas, so the same code can show a different city, account or chart in each place.

dash.props: Readonly<Record<string, unknown>>
dash.onProps(cb: (props: Record<string, unknown>) => void): () => void

Example

Declare two props in manifest.json:

{
  "name": "Weather",
  "size": { "default": [3, 3] },
  "props": {
    "city": { "type": "string", "label": "City", "default": "London" },
    "units": {
      "type": "select",
      "label": "Units",
      "options": ["metric", "imperial"],
      "default": "metric"
    }
  }
}

Read them when the pane starts, and again whenever they change:

function render(props) {
  document.querySelector('#title').textContent = String(props.city) + ' · ' + String(props.units);
}

render(dash.props);
dash.onProps(render);

Prop types

Each prop has a type, a label (1 to 80 characters, shown next to its field) and an optional default.

Type	Value	Field on the canvas
string	Text up to 1,000 characters.	Text field
number	A finite number, within min and max when you set them.	Number field
boolean	true or false.	Checkbox
select	One of options: 1 to 50 options, each 1 to 80 characters.	Drop-down
string[]	A list of up to 50 strings, each up to 1,000 characters.	Text area, one a line

A prop name starts with a letter, then letters, digits or _, up to 64 characters. A pane can declare up to 30 props. The manifest reference has the full rules.

Setting values

• On a canvas: switch the canvas to Edit and click the pane. The settings panel on the right has a Props section with one field for each prop. Each valid change reaches the running pane as you make it, without a reload. A value that breaks the prop’s rules shows an error under its field and is not sent.
• In the editor: the props form under the preview sets values for the preview only.

Behaviour

• dash.props holds every declared prop that has a valid saved value or a default. A prop with neither is missing, so check for undefined.
• If you change a prop’s definition in the manifest, a saved value that no longer fits falls back to the default. Props the manifest no longer declares are left out.
• dash.props is read-only. When a value changes, the whole object is replaced: dash.props returns the new one and each onProps callback receives it.
• onProps is not called when the pane starts. Read dash.props for the first render, as in the example.
• onProps returns a function that removes the callback.
• Props are not secret. They are stored as plain values and the pane’s code reads them. Keep API keys in secrets.

Errors

Reading dash.props never fails. dash.onProps throws a DashError straight away in one case:

Code	Why
VALIDATION_FAILED	cb is not a function.

An error thrown inside cb is reported like any uncaught error in the pane.