Display

Class: FxDisplay · Tag: <fx-display> · Related: FxDisplayRegion (<fx-display-region>)

The <fx-display> and <fx-display-region> components render HMI read-out panels. They are designed to display telemetry, status values, and clocks with high visual stability and customizable typography.

---

Installation

import '@salsafx/ui';

Interactive preview:

Labeled

Labeled · Default

Multi

Row

Column

Medium

Caution

Live values (such as clocks or fast-changing telemetry) change glyph widths as digits update. To prevent the shell or surrounding layout from jittering, always define a fixed box size or use a value template.

Typography

The visual style of the readout is set with the typography attribute:

• classic — Standard system UI style.
• segmented — Classic 7-segment digital style (default).
• modern — Futuristic, high-tech geometric style.

Classic

Segmented

Modern

<fx-display
    label="Temp"
    value="384.2"
    suffix="°C"
    value-template="888.8"
    typography="classic"
></fx-display>

<fx-display
    label="Temp"
    value="384.2"
    suffix="°C"
    value-template="888.8"
    typography="segmented"
></fx-display>

<fx-display
    label="Temp"
    value="384.2"
    suffix="°C"
    value-template="888.8"
    typography="modern"
></fx-display>

Themes

The outer shell theme is set with the theme attribute: dark (default) or light. Glow intensity can be configured using glow: none | small (default) | medium | large | x-large.

Dark · Default

Light

<fx-display
    label="Temp"
    value="384.2"
    suffix="°C"
    value-template="888.8"
    theme="dark"
></fx-display>

<fx-display
    label="Temp"
    value="384.2"
    suffix="°C"
    value-template="888.8"
    theme="light"
></fx-display>

Mixed Sizes & Nested Regions

You can combine multiple <fx-display-region> elements inside a single <fx-display> host. Attributes like typography, theme, size, and colors are automatically inherited by nested regions unless overridden.

Segmented · Default

Modern · Host → Regions

<fx-display
    layout="horizontal"
    gap="12px"
>
    <div style="display: flex; flex-direction: column; justify-content: space-between; gap: 8px;">
        <fx-display-region
            label="O₂"
            value="98"
            suffix="%"
            value-template="888"
            size="small"
        ></fx-display-region>
        <fx-display-region
            label="Amps"
            value="12.0"
            suffix="A"
            value-template="88.8"
            size="small"
        ></fx-display-region>
    </div>
    <fx-display-region
        label="Temp"
        value="384.2"
        suffix="°C"
        value-template="888.8"
        size="xx-large"
    ></fx-display-region>
</fx-display>

<fx-display
    layout="horizontal"
    gap="12px"
    typography="modern"
>
    <div style="display: flex; flex-direction: column; justify-content: space-between; gap: 8px;">
        <fx-display-region
            label="O₂"
            value="98"
            suffix="%"
            value-template="888"
            size="small"
        ></fx-display-region>
        <fx-display-region
            label="Amps"
            value="12.0"
            suffix="A"
            value-template="88.8"
            size="small"
        ></fx-display-region>
    </div>
    <fx-display-region
        label="Temp"
        value="384.2"
        suffix="°C"
        value-template="888.8"
        size="xx-large"
    ></fx-display-region>
</fx-display>

---

Content Layout

The content-layout attribute controls how the label, prefix, value, and suffix are arranged:

• labeled — Label on top, prefix/value/suffix in a row (default).
• row — Label and value group side by side.
• column — Label on top; prefix, value, and suffix stacked vertically.

Multi-Column Layouts

Arrange multiple regions in columns using standard CSS flexbox wrappers inside the display.

<fx-display
    layout="horizontal"
    gap="12px"
    size="small"
>
    <div style="display: flex; flex-direction: column; gap: 12px;">
        <fx-display-region
            label="Oxygen"
            value="98"
            suffix="%"
            value-template="888"
        ></fx-display-region>
        <fx-display-region
            label="Clock"
            value="11:22"
            value-template="88:88"
        ></fx-display-region>
    </div>
    <div style="display: flex; flex-direction: column; gap: 12px;">
        <fx-display-region
            label="Carbon"
            value="0.03"
            suffix="ppm"
            value-template="8.88"
        ></fx-display-region>
        <fx-display-region
            label="Status"
            value="ONLINE"
            value-template="OFFLINE"
        ></fx-display-region>
    </div>
</fx-display>

Icons

Icons can be added to regions via the icon attribute or by slotting an <fx-icon> child with slot="start" or slot="end". Without size / color, the icon inherits size and color from the region.

<fx-display
    layout="vertical"
    gap="12px"
    size="small"
    region-align="left"
>
    <fx-display-region
        label="Oxygen"
        value="98"
        suffix="%"
        value-template="888"
    >
        <fx-icon slot="start" icon="fa-solid fa-wind"></fx-icon>
    </fx-display-region>
    <fx-display-region
        label="Power"
        value="12.0"
        suffix="A"
        value-template="88.8"
    >
        <fx-icon slot="start" icon="fa-solid fa-bolt"></fx-icon>
    </fx-display-region>
    <fx-display-region
        label="Temp"
        value="36.6"
        suffix="°C"
        value-template="88.8"
    >
        <fx-icon slot="start" icon="fa-solid fa-sun"></fx-icon>
    </fx-display-region>
    <fx-display-region
        label="Status"
        value="ONLINE"
        value-template="OFFLINE"
        foreground-color="#4ade80"
    ></fx-display-region>
</fx-display>

Sizes

Standard size tokens from x-small to xx-large:

<fx-display label="XS" value="12" suffix="%" value-template="88" size="x-small"></fx-display>
<fx-display label="S" value="12" suffix="%" value-template="88" size="small"></fx-display>
<fx-display label="M" value="12" suffix="%" value-template="88" size="medium"></fx-display>
<fx-display label="L" value="12" suffix="%" value-template="88" size="large"></fx-display>
<fx-display label="XL" value="12" suffix="%" value-template="88" size="x-large"></fx-display>
<fx-display label="XXL" value="12" suffix="%" value-template="88" size="xx-large"></fx-display>

Custom numeric size (64 → 64px value):

<fx-display label="64px" value="12" suffix="%" value-template="88" size="64"></fx-display>

---

Layout Stability & Sizing

To keep your HMI layout pixel-perfect and prevent elements from shifting when values update, use one of the following sizing strategies.

Fixed Size (CSS-driven)

Set explicit dimensions on <fx-display> or <fx-display-region> using standard CSS styles or custom CSS properties:

<fx-display
    style="--fx-display-width: 200px; overflow: hidden;"
    label="UTC"
    value="12:34:56"
></fx-display>

<fx-display
    style="width: 200px; height: 80px; overflow: hidden;"
    label="UTC"
    value="12:34:56"
></fx-display>

<fx-display
    layout="horizontal"
    gap="12px"
>
    <fx-display-region
        style="--fx-display-region-width: 120px; overflow: hidden;"
        label="O₂"
        value="98"
        suffix="%"
    ></fx-display-region>
    <fx-display-region
        style="width: 160px; overflow: hidden;"
        label="Temp"
        value="384.2"
        suffix="°C"
    ></fx-display-region>
</fx-display>

Value Template (Intrinsic Sizing)

If you prefer intrinsic sizing but want to prevent jumping, pass the value-template attribute with the widest expected value pattern (e.g., 88:88:88 or 888.8).

The component will automatically calculate the maximum required width (including prefix, suffix, and icon) and keep the layout perfectly stable. CSS styles will still take precedence if defined.

Clocks & Timers:

<!-- HH:MM:SS -->
<fx-display
    value-template="88:88:88"
    label="UTC"
    value="12:34:56"
></fx-display>

<!-- HH:MM -->
<fx-display
    value-template="88:88"
    label="UTC"
    value="12:34"
></fx-display>

Telemetry Readouts:

<fx-display
    value-template="888.8"
    prefix="±"
    value="12.4"
    suffix="°C"
></fx-display>

Individual Regions:

<fx-display
    layout="horizontal"
    gap="12px"
>
    <fx-display-region
        value-template="888"
        label="O₂"
        value="98"
        suffix="%"
    ></fx-display-region>
    <fx-display-region
        value-template="888.8"
        label="Temp"
        value="36.6"
        suffix="°C"
    ></fx-display-region>
</fx-display>

---

Live Clock

<digital-live-clock> is a small widget on top of <fx-display> that ticks once per second (UTC by default, with a built-in 88:88:88 value template).

UTC · Small

System · Medium

Mission · Large

<digital-live-clock
    label="UTC"
    size="small"
    foreground-color="#10b981"
></digital-live-clock>

---

API Reference

<fx-display> Properties

Property	Attribute	Type	Default	Description
layout	layout	String	"vertical"	Arrangement layout of the nested regions (“horizontal”, “vertical”, or “grid”).
gap	gap	String	"4px"	Spacing gap between regions.
gridTemplate	grid-template	String	""	Grid template columns when layout is set to grid.
size	size	String	"small"	Size of the display (preset token or custom value).
hasShell	has-shell	Boolean	true	Shows the outer shell background and border.
theme	theme	String	"dark"	Color theme preset (“light” or “dark”).
disabled	disabled	Boolean	false	Disables the control and prevents user interaction.
contentLayout	content-layout	String	"labeled"	Default layout for nested regions (“row”, “labeled”, or “column”).
backgroundColor	background-color	String	""	Shell background color override.
border	border	String	""	Shell border override.
borderRadius	border-radius	String	""	Shell corner radius override.
padding	padding	String	""	Shell padding override.
typography	typography	String	"segmented"	Typography style preset (“classic”, “segmented”, or “modern”).
glow	glow	String	"small"	Glow intensity of the displayed text (“none”, “small”, “medium”, “large”, or “x-large”).
isSelectable	is-selectable	Boolean	false	Allows text selection.
foregroundColor	foreground-color	String	"#38bdf8"	Value text color.
labelColor	label-color	String	"#9ca3af"	Label text color.
align	region-align	String	"center"	Default region alignment inside the display.
label / value / suffix	same	String	""	Label, value, and suffix when using a single region.
valueTemplate	value-template	String	""	Template used to reserve space for the widest expected value (e.g., "88:88").

<fx-display-region> Properties

Property	Attribute	Type	Default	Description
contentLayout	content-layout	String	"labeled"	Layout of the region content (“row”, “labeled”, or “column”).
size	size	String	"small"	Size of the region (preset token or custom value).
label	label	String	""	Caption text.
value	value	String	""	Primary readout value.
valueTemplate	value-template	String	""	Template used to reserve space for the widest expected value in this region (e.g., "888.8").
prefix / suffix	same	String	""	Text before or after the value.
foregroundColor	foreground-color	String	"#38bdf8"	Value text color.
backgroundColor	background-color	String	""	Region background color override.
typography	typography	String	"segmented"	Typography style preset (“classic”, “segmented”, or “modern”).
align	align	String	"center"	Alignment inside the region.
icon	icon	String	""	Icon-font class list or a path ending in .svg.
iconSide	icon-side	String	"left"	Side of the value to display the icon (“left”, “right”, “top”, or “bottom”).

<fx-icon>

See Icon for the full API. Without size / color, the icon inherits from the parent region.

Slots

Name	Description
— (default)	Nested <fx-display-region> children, or manual icon markup inside <fx-icon>.
start / end (on <fx-display-region>)	Content before or after the value (including <fx-icon>).
icon (on region / push-button / card)	Icon slot; accept <fx-icon> or raw <i>.

CSS Custom Properties

Property	Default	Description
--fx-display-width	(unset)	<fx-display> host width.
--fx-display-height	(unset)	<fx-display> host height.
--fx-display-region-width	(unset)	<fx-display-region> width.
--fx-display-region-height	(unset)	<fx-display-region> height.
--fx-display-shell-background	from theme	Shell fill.
--fx-display-shell-border	#334155	Shell border.
--fx-display-value-size	size token	Value font size.
--fx-display-label-size	size token	Label font size.
--fx-display-glow	from glow	Text glow intensity.

---

Object Hierarchy

classDiagram
    direction TB
    class FxElement
    class FxDisplay

    FxElement <|-- FxDisplay

See also Architecture.