Layouts (SD+)

Layout of information on the touch display.

Layouts describe how information is shown on the Stream Deck + touch display. There are built-in pre-defined layouts or create a custom layout JSON file. The layout name or path to the custom layout json file is defined in the manifest. The layout can also be dynamically changed using the setFeedbackLayout event.

Slot

A slot is made up of a combination of one dial and one portion of the touch display. This portion of the touch display has a resolution of 200 x 100 px. Users have access to customize the icon and background in this space. Developers can customize this space for their plugins using layouts.

Built-in Layouts

Built-in layouts are predefined in Stream Deck and can be referenced using the layout id property.

Icon Layout ($X1)

The default layout. To use this layout set the layout property to $X1 the Encoder.

{
  "id": "$X1",
  "items": [
    {
      "key": "title",
      "type": "text",
      "rect": [16, 10, 136, 24],
      "font": { "size": 16, "weight": 600 },
      "alignment": "left"
    },
    {
      "key": "icon",
      "type": "pixmap",
      "rect": [76, 40, 48, 48]
    }
  ]
}

Canvas Layout ($A0)

The layout best suited for custom images with a title. To use this layout set the layout property to $A0 in the Encoder.

{
  "id": "$A0",
  "items": [
    {
      "key": "full-canvas",
      "type": "pixmap",
      "rect": [0, 0, 200, 100]
    },
    {
      "key": "title",
      "type": "text",
      "rect": [16, 10, 136, 24],
      "zOrder": 1,
      "font": { "size": 16, "weight": 600 },
      "alignment": "left"
    },
    {
      "key": "canvas",
      "type": "pixmap",
      "rect": [16, 34, 136, 54],
      "zOrder": 1
    }
  ]
}

Value Layout ($A1)

The layout best suited for representing a single value. To use this layout set the layout property to $A1 in the Encoder.

{
  "id": "$A1",
  "items": [
    {
      "key": "title",
      "type": "text",
      "rect": [16, 10, 136, 24],
      "font": { "size": 16, "weight": 600 },
      "alignment": "left"
    },
    {
      "key": "icon",
      "type": "pixmap",
      "rect": [16, 40, 48, 48]
    },
    {
      "key": "value",
      "type": "text",
      "rect": [76, 40, 108, 32],
      "font": { "size": 24, "weight": 600 },
      "alignment": "right"
    }
  ]
}

Indicator Layout ($B1)

The layout best suited for representing a single value range. To use this layout set the layout property to $B1 in the Encoder.

{
  "id": "$B1",
  "items": [
    {
      "key": "title",
      "type": "text",
      "rect": [16, 10, 136, 24],
      "font": { "size": 16, "weight": 600 },
      "alignment": "left"
    },
    {
      "key": "icon",
      "type": "pixmap",
      "rect": [16, 40, 48, 48]
    },
    {
      "key": "value",
      "type": "text",
      "rect": [76, 40, 108, 32],
      "font": { "size": 24, "weight": 600 },
      "alignment": "right"
    },
    {
      "key": "indicator",
      "type": "bar",
      "rect": [76, 74, 108, 12],
      "value": 0,
      "subtype": 4,
      "border_w": 0
    }
  ]
}

Gradient Indicator Layout ($B2)

The layout best suited for representing a single value range, where the data can be further explained using color. To use this layout set the layout property to $B2 in the Encoder.

{
  "id": "$B2",
  "items": [
    {
      "key": "title",
      "type": "text",
      "rect": [16, 10, 136, 24],
      "font": { "size": 16, "weight": 600 },
      "alignment": "left"
    },
    {
      "key": "icon",
      "type": "pixmap",
      "rect": [16, 40, 48, 48]
    },
    {
      "key": "value",
      "type": "text",
      "rect": [76, 40, 108, 32],
      "font": { "size": 24, "weight": 600 },
      "alignment": "right"
    },
    {
      "key": "indicator",
      "type": "gbar",
      "rect": [76, 74, 108, 20],
      "value": 0,
      "subtype": 4,
      "bar_h": 12,
      "border_w": 0,
      "bar_bg_c": "0:#ff0000,0.33:#a6d4ec,0.66:#f4b675,1:#00ff00"
    }
  ]
}

Double Indicator Layout ($C1)

The layout best suited for representing two value ranges.To use this layout set the layout property to $C1 in the Encoder.

{
  "id": "$C1",
  "items": [
    {
      "key": "title",
      "type": "text",
      "rect": [16, 10, 136, 24],
      "font": { "size": 16, "weight": 600 },
      "alignment": "left"
    },
    {
      "key": "icon1",
      "type": "pixmap",
      "rect": [16, 40, 24, 24]
    },
    {
      "key": "icon2",
      "type": "pixmap",
      "rect": [16, 68, 24, 24]
    },
    {
      "key": "indicator1",
      "type": "bar",
      "rect": [48, 46, 136, 12],
      "value": 0,
      "subtype": 4,
      "border_w": 0
    },
    {
      "key": "indicator2",
      "type": "bar",
      "rect": [48, 74, 136, 12],
      "value": 0,
      "subtype": 4,
      "border_w": 0
    }
  ]
}

Custom Layouts

In addition to the built in layouts you can define custom layouts in a separate json file. Custom layouts are comprised of a combination of items. These items are sized and positioned using the required rect and optional zOrder properties.

⚠️ Items with the same zOrder must NOT overlap or they will not be displayed.

Example JSON

{
  "id": "com.elgato.example.action2.layout",
  "items": [
    {
      "key": "title",
      "type": "text",
      "rect": [16, 10, 136, 24],
      "font": { "size": 16, "weight": 600 },
      "alignment": "left"
    },
    {
      "key": "icon",
      "type": "pixmap",
      "rect": [76, 40, 48, 48]
    }
  ]
}

Members

Members	Type	Description
id	Required	The layout name must be unique, i.e. not to collide with built-in layouts or ones defined by other plug-ins.
items	Required	Array of item objects (see below).

Items

Items are drawable elements that make up a layout on the Stream Deck + touch display. Items with the same zOrder must NOT overlap or they will not be displayed. Item members marked as Editable can be updated from the plugin using the setFeedback event.

PIXMAP

Used to display an image. The image is scaled with respect to rect. Members marked as Editable can be updated from the plugin using the setFeedback event.

{
  "key": "logo",
  "type": "pixmap",
  "rect": [60, 20, 50, 50]
}

Members	Type	Description	Editable
key	Required	The name of the defined item. setFeedback uses it as a key to identify the item of the layout (this has to be unique).	false
type	Required	Value is pixmap	false
rect	Required	The array holding the rectangle coordinates (x, y, w, h) of the defined item. Items with the same zOrder must NOT overlap. The rectangle must be inside of slot coordinates - (0, 0) x (200, 100).	false
value	Required	A string used to provide an image path or image itself as a base64 encoded data.	true
zOrder	Optional	The non-negative integer in a range [0, 700) defining the z-order of the item. Items with the same zOrder must NOT overlap. Defaulted to zero.	true
enabled	Optional	A boolean value which is true when the defined item is enabled (i.e. visible). Defaulted to true.	true
opacity	Optional	A real number in a range [0.0, 1.0] determining the opacity level of the item. Defaulted to 1.	true
background	Optional	The string used to define the item background fill color. Defaulted to transparent.	true

BAR

Bar shape filled with the specified color. Members marked as Editable can be updated from the plugin using the setFeedback event.

{
  "key": "sdk-bar",
  "type": "bar",
  "subtype": 4,
  "rect": [60, 20, 100, 20],
  "value": 55,
  "range": {
    "min": 0,
    "max": 100
  }
}

Members	Type	Description	Editable
key	Required	The name of the defined item. setFeedback uses it as a key to identify the item of the layout (this has to be unique).	false
type	Required	Value is bar	false
rect	Required	The array holding the rectangle coordinates (x, y, w, h) of the defined item. Items with the same zOrder must NOT overlap. The rectangle must be inside of slot coordinates - (0, 0) x (200, 100).	false
value	Required	An integer value in the range [0, 100] to display an indicator.	true
range	Optional	Defines the range of the value the bar represents, e.g. 0-20, 0-100, etc.	true
subtype	Optional	An integer value to represent shape: 0 - rectangle, 1 - double rectangle, 2 - trapezoid, 3 - double trapezoid, 4 - groove (groove is recommended design for SD+)	true
zOrder	Optional	The non-negative integer in a range [0, 700) defining the z-order of the item. Items with the same zOrder must NOT overlap. Defaulted to zero.	true
enabled	Optional	A boolean value which is true when the defined item is enabled (i.e. visible). Defaulted to true.	true
opacity	Optional	A real number in a range [0.0, 1.0] determining the opacity level of the item. Defaulted to 1.	true
background	Optional	The string used to define the item background fill color. Defaulted to transparent.	true
border_w	Optional	An integer value for border width. Defaulted to 2	true
bar_bg_c	Optional	A string value to determine bar color or gradient. Defaulted to darkGray	true
bar_border_c	Optional	A string value for bar border color. Defaulted to white	true
bar_fill_c	Optional	A string value for bar indicator fill color. Defaulted to white	true

Range

Members marked as Editable can be updated from the plugin using the setFeedback event.

Members	Type	Description	Editable
min	Required	Minimum value of the bar. Defaults to 0.	true
max	Required	Maximum value of the bar. Defaults to 100.	true

GBAR

Bar shape with a triangle indicator below. Members marked as Editable can be updated from the plugin using the setFeedback event.

{
  "key": "sdk-gbar",
  "type": "gbar",
  "subtype": 4,
  "rect": [60, 20, 100, 20],
  "bar_h": 12,
  "value": 55,
  "range": {
    "min": 0,
    "max": 100
  }
}

Members	Type	Description	Editable
key	Required	The name of the defined item. setFeedback uses it as a key to identify the item of the layout (this has to be unique).	false
type	Required	Value is gbar	false
rect	Required	The array holding the rectangle coordinates (x, y, w, h) of the defined item. Items with the same zOrder must NOT overlap. The rectangle must be inside of slot coordinates - (0, 0) x (200, 100).	false
value	Required	An integer value in the range [0, 100] to display an indicator.	true
range	Optional	Defines the range of the value the bar represents, e.g. 0-20, 0-100, etc.	true
subtype	Optional	An integer value to represent shape: 0 - rectangle, 1 - double rectangle, 2 - trapezoid, 3 - double trapezoid, 4 - groove (groove is recommended design for SD+)	true
zOrder	Optional	The non-negative integer in a range [0, 700) defining the z-order of the item. Items with the same zOrder must NOT overlap. Defaulted to zero.	true
enabled	Optional	A boolean value which is true when the defined item is enabled (i.e. visible). Defaulted to true.	true
opacity	Optional	A real number in a range [0.0, 1.0] determining the opacity level of the item. Defaulted to 1.	true
background	Optional	The string used to define the item background fill color. Defaulted to transparent.	true
border_w	Optional	An integer value for border width. Defaulted to 2	true
bar_bg_c	Optional	A string value to determine bar color or gradient. Defaulted to darkGray	true
bar_border_c	Optional	A string value for bar border color. Defaulted to white	true
bar_h	Optional	An integer value for the indicator's groove height. The indicator height will be adjusted to fit in the items height. Defaulted to 10.	true

Range

Members marked as Editable can be updated from the plugin using the setFeedback event.

Members	Type	Description	Editable
min	Required	Minimum value of the bar. Defaults to 0.	true
max	Required	Maximum value of the bar. Defaults to 100.	true

TEXT

A text label. Members marked as Editable can be updated from the plugin using the setFeedback event.

{
  "key": "sdk-text",
  "type": "text",
  "rect": [30, 40, 140, 24],
  "font": { "size": 16, "weight": 600 },
  "value": "Stream Deck SDK",
  "text-overflow": "ellipsis"
}

Members	Type	Description	Editable
key	Required	The name of the defined item. setFeedback uses it as a key to identify the item of the layout (this has to be unique).	false
type	Required	Value is text	false
rect	Required	The array holding the rectangle coordinates (x, y, w, h) of the defined item. Items with the same zOrder must NOT overlap. The rectangle must be inside of slot coordinates - (0, 0) x (200, 100).	false
value	Required	A string value.	true
zOrder	Optional	The non-negative integer in a range [0, 700) defining the z-order of the item. Items with the same zOrder must NOT overlap. Defaulted to zero. Note that if the key for the text item is title the styles selected in the property inspector will override this property.	true
enabled	Optional	A boolean value which is true when the defined item is enabled (i.e. visible). Defaulted to true. Note that if the key for the text item is title the styles selected in the property inspector will override this property.	true
opacity	Optional	A real number in a range [0.0, 1.0] determining the opacity level of the item. Defaulted to 1. Note that if the key for the text item is title the styles selected in the property inspector will override this property.	true
background	Optional	The string used to define the item background fill color. Defaulted to transparent. Note that if the key for the text item is title the styles selected in the property inspector will override this property.	true
font	Optional	An object describing the text.	true
color	Optional	A string describing the color of text. Defaulted to white. Note that if the key for the text item is title the styles selected in the property inspector will override this property.	true
alignment	Optional	A string describing the text alignment in the rectangle. Values include: left, center, or right. Defaulted to center. Note that if the key for the text item is title the styles selected in the property inspector will override this property.	true
text-overflow	Optional	Defines how overflowing text should be rendered on the layout. "ellipsis", truncates the text prior to the boundary of the element, and adds an ellipsis (…) to the end (default). "clip", truncates the text at the boundary of the element. "fade", applies a fade-gradient over the end of the text.	true

Font

Members marked as Editable can be updated from the plugin using the setFeedback event.

Members	Type	Description	Editable
size	Optional	An integer font pixel size. Note that if the key for the text item is title the styles selected in the property inspector will override this property.	true
weight	Optional	Weight of the font (an integer value between 100 and 1000 or the string with a name of typographical weight). Note that if the key for the text item is title the styles selected in the property inspector will override this property.	true