Props

Apps can expose a list of custom UI fields allowing non-technical people to configure or change the way your apps work.

Configure

To generate custom UI for your app, configure the fields at the top of your app’s script like this:

app.configure([
  {
    key: 'name',
    type: 'text',
    label: 'Name',
  }
])

The example above will create a text input for you to enter a name.

Props

Apps have a global props variable for you to read back the values entered in custom fields.

props.name

Fields

Text

A text input

{
  type: 'text',
  key: String,           // the key on `props` to set this value
  label: String,         // the label for the text input
  placeholder: String,   // an optional placeholder displayed inside the input
  initial: String,       // the initial value to set if not configured
}

Textarea

A multi-line textarea input

{
  type: 'textarea',
  key: String,           // the key on `props` to set this value
  label: String,         // the label for the text input
  placeholder: String,   // an optional placeholder displayed inside the input
  initial: String,       // the initial value to set if not configured
}

Number

A number input. Also supports math entry and up/down stepping.

{
  type: 'number',
  key: String,           // the key on `props` to set this value
  label: String,         // the label for the text input
  dp: Number,            // the number of decimal places allowed (default = 0)
  min: Number,           // the minimum value allowed (default = -Infinity)
  max: Number,           // the maximum value allowed (default = Infinity)
  step: Number,          // the amount incremented/decrement when pressing up/down arrows (default = 1)
  initial: Number,       // the initial value to set if not configured (default = 0)
}

Switch

A switch input

{
  type: 'switch',
  key: String,           // the key on `props` to set this value
  label: String,         // the label for the text input
  options: [
    {
      label: String,     // the label to show on this switch item
      value: String,     // the value to set on the props when selected
    }
  ],
  initial: String,       // the initial value to set if not configured
}

File

A file field for selecting and uploading additional assets that can be used by your app.

{
  type: 'file',
  key: String,           // the key on `props` to set this value
  label: String,         // the label for the text input
  kind: String,          // the kind of file, must be one of: avatar, emote, model, texture, hdr, audio
}

Note that the value set on props is an object that looks like this:

{
  type: String,         // the type of file (avatar, emote, model, texture, hdr, audio)
  name: String,         // the original files name
  url: String,          // the url to the file
}

The type of file you collect depends on how you would use it. For example you can use audio files with an audio node:

const audio = app.create('audio', {
  src: props.audio?.url
})
audio.play()

Section

A simple section header to help group fields together

{
  type: 'section',
  key: String,           // a unique `key` to represent this section
  label: String,         // the label for the section header
}