Layouts
Layouts are customizable interfaces used by the touch strip found on Stream Deck +, and the Infobar found on Stream Deck Neo. Layouts are defined as JSON files distributed with your plugin, and can be updated programmatically whilst your plugin is running.
Device Sizes
The canvas size of a layout varies depending on the device it will be rendered on, these sizes are:
- Stream Deck + — 200 × 100 px
- Stream Deck + XL — 200 × 100 px
- Stream Deck Neo Infobar — 232 × 50 px
In the context of Stream Deck + (Classic | XL) , the layout's canvas is a portion of the touch strip associated with a corresponding dial. Plugins cannot render across the entire touch strip.
JSON Schema
A JSON schema is available for layout JSON files, providing intellisense and validation, and is available at the following URL:
https://schemas.elgato.com/streamdeck/plugins/layout.jsonYou can reference this URL using the $schema property within your layout JSON file:
{
"$schema": "https://schemas.elgato.com/streamdeck/plugins/layout.json",
"id": "CustomLayout",
"items": [
// ...
]
}TypeScript Declaration
type Layout = {
controller?: "Encoder" | "Neo";
id: string;
items: (
| {
background?: string;
bar_bg_c?: string;
bar_border_c?: string;
bar_fill_c?: string;
border_w?: number;
enabled?: boolean;
key: string;
opacity?: 0 | 0.1 | 0.2 | 0.3 | 0.4 | 0.5 | 0.6 | 0.7 | 0.8 | 0.9 | 1;
range?: {
max: number;
min: number;
};
rect: [x: number, y: number, width: number, height: number];
subtype?: 0 | 1 | 2 | 3 | 4;
type: "bar";
value: number;
zOrder?: number;
}
| {
background?: string;
bar_bg_c?: string;
bar_border_c?: string;
bar_fill_c?: string;
bar_h?: number;
border_w?: number;
enabled?: boolean;
key: string;
opacity?: 0 | 0.1 | 0.2 | 0.3 | 0.4 | 0.5 | 0.6 | 0.7 | 0.8 | 0.9 | 1;
range?: {
max: number;
min: number;
};
rect: [x: number, y: number, width: number, height: number];
subtype?: 0 | 1 | 2 | 3 | 4;
type: "gbar";
value: number;
zOrder?: number;
}
| {
background?: string;
enabled?: boolean;
key: string;
opacity?: 0 | 0.1 | 0.2 | 0.3 | 0.4 | 0.5 | 0.6 | 0.7 | 0.8 | 0.9 | 1;
rect: [x: number, y: number, width: number, height: number];
type: "pixmap";
value?: string;
zOrder?: number;
}
| {
alignment?: "center" | "left" | "right";
background?: string;
color?: string;
enabled?: boolean;
font?: {
size?: number;
weight?: number;
};
key: string;
opacity?: 0 | 0.1 | 0.2 | 0.3 | 0.4 | 0.5 | 0.6 | 0.7 | 0.8 | 0.9 | 1;
rect: [x: number, y: number, width: number, height: number];
"text-overflow"?: "clip" | "ellipsis" | "fade";
type: "text";
value?: string;
zOrder?: number;
}
)[];
};Definitions
Layout
Defines the structure of a custom layout file.
Properties
Bar
Bar layout item used to render a horizontal bar with a filler, e.g. a progress bar. The amount to fill the bar by can be specified by setting the value.
Properties
background: string
Background color represented as a named color, hexadecimal value, or gradient. Gradients can be defined by specifying multiple color-stops separated by commas, in the following
format [{offset}:{color}[,]].
Examples:
- "pink"
- "#204cfe" (Elgato blue)
- "0:#ff0000,0.5:yellow,1:#00ff00" (Gradient)
key: stringRequired
Unique name used to identify the layout item. When calling setFeedback this value should be used as the key as part of the object that represents the feedback.
Note: The key of the layout item cannot be changed at runtime.
opacity: 0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1
Defines the opacity of the item being shown based on a single-decimal value ranging from 0..1, e.g. 0.1, 0.2, etc. with 0 being invisible and 1 being fully visible.
Default is 1.
rect: [x: number, y: number, width: number, height: number]Required
The coordinates of the item, represented as [x, y, width, height].
Items must be within the bounds of the Stream Deck device the layout is intended for, and must
not be overlapping with other items. For items that may overlap, consider using zOrder.
Stream Deck device layout sizes:
- Stream Deck +, 200 x 100 px
- Stream Deck Neo, 232 x 50 px
Note: The rect of the layout item cannot be changed at runtime.
type: "bar"Required
Type of layout item this instance represents, e.g. "pixmap", "bar", etc.
Note: The type of the layout item cannot be changed at runtime.
zOrder: number
Z-order of the item, used to layer items within a layout; must be between 0-700. Items with the same zOrder must not have an overlapping rect. Default is 0.
bar_bg_c: string
Bar background color represented as a named color, hexadecimal value, or gradient. Default is darkGray. Gradients can be defined by specifying multiple color-stops separated
by commas, in the following format [{offset}:{color}[,]].
Examples:
- "pink"
- "#204cfe" (Elgato blue)
- "0:#ff0000,0.5:yellow,1:#00ff00" (Gradient)
bar_border_c: string
Border color represented as a named color, or hexadecimal value. Default is white.
Examples:
- "pink"
- "#204cfe" (Elgato blue)
bar_fill_c: string
Fill color of the bar represented as a named color, hexadecimal value, or gradient. Default is white. Gradients can be defined by specifying multiple color-stops separated
by commas, in the following format [{offset}:{color}[,]].
Examples:
- "pink"
- "#204cfe" (Elgato blue)
- "0:#ff0000,0.5:yellow,1:#00ff00" (Gradient)
range: Range
Defines the range of the value the bar represents, e.g. 0-20, 0-100, etc.
subtype: 0, 1, 2, 3, 4
Sub-type used to determine the type of bar to render. Default is {@link BarSubType.Groove} (4).
Options
- Rectangle (0)
- DoubleRectangle (1)
- Trapezoid (2)
- DoubleTrapezoid (3)
- Groove (4)
value: numberRequired
Value used to determine how much of the bar is filled. Correlates with the item's range if specified in the layout's JSON definition; default range is 0..100.
GBar
Bar layout item used to render a horizontal bar with an indicator represented as a triangle beneath the bar. The location of the indicator can be specified by setting the value.
Properties
background: string
Background color represented as a named color, hexadecimal value, or gradient. Gradients can be defined by specifying multiple color-stops separated by commas, in the following
format [{offset}:{color}[,]].
Examples:
- "pink"
- "#204cfe" (Elgato blue)
- "0:#ff0000,0.5:yellow,1:#00ff00" (Gradient)
key: stringRequired
Unique name used to identify the layout item. When calling setFeedback this value should be used as the key as part of the object that represents the feedback.
Note: The key of the layout item cannot be changed at runtime.
opacity: 0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1
Defines the opacity of the item being shown based on a single-decimal value ranging from 0..1, e.g. 0.1, 0.2, etc. with 0 being invisible and 1 being fully visible.
Default is 1.
rect: [x: number, y: number, width: number, height: number]Required
The coordinates of the item, represented as [x, y, width, height].
Items must be within the bounds of the Stream Deck device the layout is intended for, and must
not be overlapping with other items. For items that may overlap, consider using zOrder.
Stream Deck device layout sizes:
- Stream Deck +, 200 x 100 px
- Stream Deck Neo, 232 x 50 px
Note: The rect of the layout item cannot be changed at runtime.
type: "gbar"Required
Type of layout item this instance represents, e.g. "pixmap", "bar", etc.
Note: The type of the layout item cannot be changed at runtime.
zOrder: number
Z-order of the item, used to layer items within a layout; must be between 0-700. Items with the same zOrder must not have an overlapping rect. Default is 0.
bar_bg_c: string
Bar background color represented as a named color, hexadecimal value, or gradient. Default is darkGray. Gradients can be defined by specifying multiple color-stops separated
by commas, in the following format [{offset}:{color}[,]].
Examples:
- "pink"
- "#204cfe" (Elgato blue)
- "0:#ff0000,0.5:yellow,1:#00ff00" (Gradient)
bar_border_c: string
Border color represented as a named color, or hexadecimal value. Default is white.
Examples:
- "pink"
- "#204cfe" (Elgato blue)
bar_fill_c: string
Fill color of the bar represented as a named color, hexadecimal value, or gradient. Default is white. Gradients can be defined by specifying multiple color-stops separated
by commas, in the following format [{offset}:{color}[,]].
Examples:
- "pink"
- "#204cfe" (Elgato blue)
- "0:#ff0000,0.5:yellow,1:#00ff00" (Gradient)
range: Range
Defines the range of the value the bar represents, e.g. 0-20, 0-100, etc.
subtype: 0, 1, 2, 3, 4
Sub-type used to determine the type of bar to render. Default is {@link BarSubType.Groove} (4).
Options
- Rectangle (0)
- DoubleRectangle (1)
- Trapezoid (2)
- DoubleTrapezoid (3)
- Groove (4)
value: numberRequired
Value used to determine how much of the bar is filled. Correlates with the item's range if specified in the layout's JSON definition; default range is 0..100.
Pixmap
Image layout item used to render an image sourced from either a local file located under the plugin's folder, or base64 encoded string. The value defines the image.
Properties
background: string
Background color represented as a named color, hexadecimal value, or gradient. Gradients can be defined by specifying multiple color-stops separated by commas, in the following
format [{offset}:{color}[,]].
Examples:
- "pink"
- "#204cfe" (Elgato blue)
- "0:#ff0000,0.5:yellow,1:#00ff00" (Gradient)
key: stringRequired
Unique name used to identify the layout item. When calling setFeedback this value should be used as the key as part of the object that represents the feedback.
Note: The key of the layout item cannot be changed at runtime.
opacity: 0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1
Defines the opacity of the item being shown based on a single-decimal value ranging from 0..1, e.g. 0.1, 0.2, etc. with 0 being invisible and 1 being fully visible.
Default is 1.
rect: [x: number, y: number, width: number, height: number]Required
The coordinates of the item, represented as [x, y, width, height].
Items must be within the bounds of the Stream Deck device the layout is intended for, and must
not be overlapping with other items. For items that may overlap, consider using zOrder.
Stream Deck device layout sizes:
- Stream Deck +, 200 x 100 px
- Stream Deck Neo, 232 x 50 px
Note: The rect of the layout item cannot be changed at runtime.
type: "pixmap"Required
Type of layout item this instance represents, e.g. "pixmap", "bar", etc.
Note: The type of the layout item cannot be changed at runtime.
zOrder: number
Z-order of the item, used to layer items within a layout; must be between 0-700. Items with the same zOrder must not have an overlapping rect. Default is 0.
value: string
Image to render; this can be either a path to a local file within the plugin's folder, a base64 encoded string with the mime type declared (e.g. PNG, JPEG, etc.), or an SVG
string.
Examples:
- "imgs/Logo.png"
- "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSI1MHB0IiBoZWlnaHQ9…"
Range
Defines the range of the value the bar represents, e.g. 0-20, 0-100, etc.
Properties
Text
Text layout item used to render text within a layout. Note, when adding a text item to the layout's JSON definition, setting the key to the "title" keyword will enable the
user to specify the font's
settings via the property inspector, and will cause setTitle to update this item.
Properties
background: string
Background color represented as a named color, hexadecimal value, or gradient. Gradients can be defined by specifying multiple color-stops separated by commas, in the following
format [{offset}:{color}[,]].
Examples:
- "pink"
- "#204cfe" (Elgato blue)
- "0:#ff0000,0.5:yellow,1:#00ff00" (Gradient)
key: stringRequired
Unique name used to identify the layout item. When calling setFeedback this value should be used as the key as part of the object that represents the feedback.
Note: The key of the layout item cannot be changed at runtime.
opacity: 0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1
Defines the opacity of the item being shown based on a single-decimal value ranging from 0..1, e.g. 0.1, 0.2, etc. with 0 being invisible and 1 being fully visible.
Default is 1.
rect: [x: number, y: number, width: number, height: number]Required
The coordinates of the item, represented as [x, y, width, height].
Items must be within the bounds of the Stream Deck device the layout is intended for, and must
not be overlapping with other items. For items that may overlap, consider using zOrder.
Stream Deck device layout sizes:
- Stream Deck +, 200 x 100 px
- Stream Deck Neo, 232 x 50 px
Note: The rect of the layout item cannot be changed at runtime.
type: "text"Required
Type of layout item this instance represents, e.g. "pixmap", "bar", etc.
Note: The type of the layout item cannot be changed at runtime.
zOrder: number
Z-order of the item, used to layer items within a layout; must be between 0-700. Items with the same zOrder must not have an overlapping rect. Default is 0.
alignment: "center", "left", "right"
Alignment of the text. Default is "center". Note, when the key of this layout item is set to "title" within the layout's JSON definition, these values will be ignored
in favour of the user's preferred title settings, as set in property inspector.
color: string
Color of the font represented as a named color, or hexadecimal value. Default is white. Note, when the key of this layout item is set to "title" within the layout's
JSON definition, these values will be ignored in favour of the user's preferred title settings, as set in property inspector.
Examples:
- "pink"
- "#204cfe" (Elgato blue)
font: object
Defines how the font should be rendered. Note, when the key of this layout item is set to "title" within the layout's JSON definition, these values will be ignored in
favour of the user's preferred title settings, as set in property inspector.
Properties
text-overflow: "clip", "ellipsis", "fade"
Defines how overflowing text should be rendered on the layout.
- clip, truncates the text at the boundary of the element (default).
- ellipsis, truncates the text prior to the boundary of the element, and adds an ellipsis (…) to the end.
- fade, applies a fade-gradient over the end of the text.