Skip to main content
DocsSmartThings APIEnterprise API
Docs

Display Types

Display types are used in Capability Presentations. They identify different visual representations that can be used to display a Capability in the SmartThings app. Each Capability Presentation view (dashboard, detail, automation) supports various display types, described here.

note

The properties of minimum and maximum as found in the Capability's definition are not automatically detected and set as the range for a given display type.

Dashboard Display Types​

pushButton​

The pushButton display type renders a Capability as a button on the dashboard. This display type requires an associated command and may have an argument to be sent.

"pushButton": {
    "command": "setButton",
    "argument": "push"
}

Switches​

There are multiple display types for switches. All switches follow a similar structure, but render differently in the SmartThings app. Available types include:

  • switch - renders with an on/off icon
  • toggleSwitch - renders with a sliding toggle
  • standbyPowerSwitch - renders with an on/standby icon
  • statelessPowerToggle - renders with a stateless on/off icon

The example dashboard switch below demonstrates a toggle switch:

"toggleSwitch": {
    "command": {
        "name": "setSwitch",
        "on": "on",
        "off": "off"
    },
    "state": {
        "value": "switch.value",
        "on": "on",
        "off": "off",
        "label": "My Switch",
    }
}

playStatus​

playStatus is similar to a switch type, but will display as a play, pause, or stop symbol in the dashboard. Rendering options include playStop and playPause. Both have a similar payload structure for describing the state of a player:

"playPause": {
    "command": {
        "name": "setPlaybackStatus",
        "play": "playing",
        "pause": "paused"
    },
    "state": {
        "value": "playbackStatus.value",
        "play": "playing",
        "pause": "paused",
        "label": "Music player: {{playbackStatus.value}}",
        "alternatives": [
            {
                "key": "playing",
                "value": "playing",
                "type": "active"
            },
            {
                "key": "paused",
                "value": "paused",
                "type": "inactive"
            }
        ]
    }
}

Detail View Display Types​

pushButton​

This display type follows the format found in the pushButton Dashboard display types.

Switches​

"switch": {
    "command": {
        "on": "on",
        "off": "off"
    },
    "state": {
        "value": "switch.value",
        "on": "on",
        "off": "off",
        "label": "{{switch.value}}",
        "alternatives": [
            {
                "key": "on",
                "value": "On",
                "type": "active"
            },
            {
                "key": "off",
                "value": "Off",
                "type": "inactive"
            }
        ]
    }
}

playPause​

"playPause": {
    "command": {
        "name": "setPlaybackStatus",
        "play": "playing",
        "pause": "paused"
    },
    "state": {
        "value": "playbackStatus.value",
        "play": "playing",
        "pause": "paused",
        "alternatives": [
            {
                "key": "playing",
                "value": "Playing",
                "type": "active"
            },
            {
                "key": "paused",
                "value": "Paused",
                "type": "inactive"
            }
        ]
    }
}

playStop​

"playStop": {
    "command": {
        "name": "setPlaybackStatus",
        "play": "playing",
        "stop": "stopped"
    },
    "state": {
        "value": "playbackStatus.value",
        "play": "playing",
        "stop": "stopped",
        "alternatives": [
            {
                "key": "playing",
                "value": "Playing",
                "type": "active"
            },
            {
                "key": "stopped",
                "value": "Stopped",
                "type": "inactive"
            }
        ]
    }
}

playStatus​

The playStatus display type follows the format found in the playStatus Dashboard display types

slider​

slider can be used to set a range of integer values, such as for displaying temperature or volume:

"slider": {
    "value": "volume.value",
    "unit": "volume.unit",
    "command": "setVolume",
    "range": [
        0,
        100
    ],
    "step": 1
}

If range is not defined in the Presentation, a range of 0-100 will be implemented by default.

note

The properties of minimum and maximum as found in the Capability's definition are not detected and set as the range in the Capability's Presentation.

list​

A list can be used to display and select a number of options available for a Capability. The list elements are described in the alternatives section of the payload. The following is an abbreviated example of a list display type for a thermostat:

"list": {
    "command": {
        "name": "setThermostatMode",
        "alternatives": [
            {
                "key": "heat",
                "value": "Heat mode"
            },
            {
                "key": "cool",
                "value": "Cool mode"
            },
            {
                "key": "fan",
                "value": "Fan mode"
            }
        ],
        "supportedValues": "supportedThermostatModes.value"
    },
    "state": {
        "value": "thermostatMode.value",
        "alternatives": [
            {
                "key": "heat",
                "value": "Heat mode"
            },
            {
                "key": "cool",
                "value": "Cool mode"
            },
            {
                "key": "fan",
                "value": "Fan mode"
            }
        ]
    }
}

textField​

textField is used for text input and display. This view will have an “Edit” button rendered in the UI. This button will pop open an input screen with a field for user text input, “Cancel”, and “OK” buttons:

"textField": {
    "command": "setLightColor",
    "value": "lightColor.value"
}

numberField​

If an integer value is used for input, consider using numberField instead of textField. A min and max value can be specified:

"numberField": {
    "command": "setVolume",
    "value": "volume.value",
    "unit": "volume.unit",
    "range": [0, 100]
}

If range is not defined in the Presentation, a range of 0-100 will be implemented by default.

note

The properties of minimum and maximum as found in the Capability's definition are not detected and set as the range in the Capability's Presentation.

stepper​

stepper is useful for incremental input changes. Instead of having the user input a temperature, the user can increase or decrease the value with a +/- icon:

  "stepper": {
    "command": {
      "name": "setVolume",
    },
    "value": "volume.value",
    "step": 1,
    "range": [0, 100]
}

state​

The state display type is used to provide information about a Capability’s state to the user and does not provide an option to control the Device:

"state": {
    "label": "{{fineDustLevel.value}} {{fineDustLevel.unit}}"
}

Automation Display Types​

Automations display types differ from dashboard and detail view types in that conditions and actions are specified separately (”value” for conditions, ”command” for actions).

slider for a condition​

"slider": {
    "value": "volume.value",
    "unit": "volume.unit",
    "range": [
        0,
        100
    ],
    "step": 1
}

slider for an action​

"slider": {
    "command": "setVolume",
    "unit": "volume.unit",
    "range": [
        0,
        100
    ],
    "step": 1
}

list for a condition​

"list": {
    "value": "thermostatMode.value",
    "alternatives": [
        {
            "key": "heat",
            "value": "Heat mode"
        },
        {
            "key": "cool",
            "value": "Cool mode"
        },
        {
            "key": "fan",
            "value": "Fan mode"
        }
    ],
    "supportedValues": "supportedThermostatMode.value"
}

list for an action​

"list": {
    "command": "setThermostatMode",
    "alternatives": [
        {
            "key": "heat",
            "value": "Heat mode"
        },
        {
            "key": "cool",
            "value": "Cool mode"
        },
        {
            "key": "fan",
            "value": "Fan mode"
        }
    ],
    "supportedValues": "supportedThermostatMode.value"
}

numberField for a condition​

"numberField": {
    "value": "volume.value",
    "unit": "volume.unit",
    "range": [0, 100]
}

numberField for an action​

"numberField": {
    "command": "setVolume",
    "unit": "volume.unit",
    "range": [0, 100]
}

textField for a condition​

"textField": {
    "value": "lightColor.value"
}

textField for an action​

"textField": {
    "command": "setLightColor",
    "range": [10, 20]
}