[comment]: # ({364afe17-7f83c4c7})
# 6 Gauge

[comment]: # ({/364afe17-7f83c4c7})

[comment]: # ({fc686620-1c93902f})
### Description

These parameters and the possible property values for the respective dashboard widget field objects allow to configure
the [*Gauge*](/manual/web_interface/frontend_sections/dashboards/widgets/gauge) widget in `dashboard.create` and `dashboard.update` methods.

::: noteimportant
Widget `fields` properties are not validated during the creation or update of a dashboard.
This allows users to modify [built-in widgets](/manual/web_interface/frontend_sections/dashboards/widgets) and create [custom widgets](/devel/modules/tutorials/widget), but also introduces the risk of creating or updating widgets incorrectly.
To ensure the successful creation or update of the *Gauge* widget, please refer to the parameter behavior outlined in the tables below.
:::

[comment]: # ({/fc686620-1c93902f})

[comment]: # ({a07c7b8d-2e17e0ed})
### Parameters

The following parameters are supported for the *Gauge* widget.

|Parameter|<|[type](/manual/api/reference/dashboard/object#dashboard-widget-field)|name|value|
|-|-----|-|-----|-------------------|
|*Refresh interval*|<|0|rf_rate|0 - No refresh;<br>10 - 10 seconds;<br>30 - 30 seconds;<br>60 - *(default)* 1 minute;<br>120 - 2 minutes;<br>600 - 10 minutes;<br>900 - 15 minutes.|
|*Item*|<|4|itemid.0|[Item](/manual/api/reference/item/get) ID.<br><br>[Parameter behavior](/manual/api/reference_commentary#parameter-behavior):<br>- *required* if *Item (Widget)* is not set|
|<|*Item (Widget)*|1|itemid.\_reference|Instead of [Item](/manual/api/reference/item/get) ID:<br>`ABCDE._itemid` - set a [compatible widget](/manual/web_interface/frontend_sections/dashboards/widgets#widget-compatibility) (with its *Reference* parameter set to "`ABCDE`") as the data source for items.<br><br>[Parameter behavior](/manual/api/reference_commentary#parameter-behavior):<br>- *required* if *Item* is not set|
|*Min*|<|1|min|Any numeric value. [Suffixes](/manual/appendix/suffixes) (e.g. "1d", "2w", "4K", "8G") are supported.<br><br>Default: "0".|
|*Max*|<|1|max|Any numeric value. [Suffixes](/manual/appendix/suffixes) (e.g. "1d", "2w", "4K", "8G") are supported.<br><br>Default: "100".|
|*Value arc*|<|1|value_arc_color|Hexadecimal color code (e.g. `FF0000`).<br><br>Default: `""` (empty).|
|*Arc background*|<|1|empty_color|Hexadecimal color code (e.g. `FF0000`).<br><br>Default: `""` (empty).|
|*Background*|<|1|bg_color|Hexadecimal color code (e.g. `FF0000`).<br><br>Default: `""` (empty).|
|*Show*|<|0|show.0|1 - Description;<br>2 - Value;<br>3 - Needle;<br>4 - Scale;<br>5 - Value arc.<br><br>Note: To configure multiple values, create a dashboard widget field object for each value with an incremented number in the property name.<br><br>Default: 1, 2, 4, 5.<br><br>Values "Needle" and "Scale" are not supported if both:<br>- no dashboard widget field object for *Show* with the value "Value arc" is set;<br>- *Show arc* [advanced configuration](#advanced-configuration) parameter is set to "Disabled".<br><br>[Advanced configuration](#advanced-configuration) parameters for *Show* options are not supported if no dashboard widget field objects with the respective values are set.|
|*Override host*|<|1|override_hostid.\_reference|`ABCDE._hostid` - set a [compatible widget](/manual/web_interface/frontend_sections/dashboards/widgets#widget-compatibility) (with its *Reference* parameter set to "`ABCDE`") as the data source for hosts;<br>`DASHBOARD._hostid` - set the dashboard [host selector](/manual/web_interface/frontend_sections/dashboards/widgets#override-host) as the data source for hosts.<br><br>This parameter is not supported if configuring the widget on a [template dashboard](/manual/api/reference/templatedashboard/object).|

[comment]: # ({/a07c7b8d-2e17e0ed})

[comment]: # ({7886dec5-1db7caf7})
#### Advanced configuration

The following advanced configuration parameters are supported for the *Gauge* widget.

::: noteclassic
The number in the *Thresholds* property name (e.g. thresholds.0.color) references the threshold place in a list, sorted in ascending order.
However, if thresholds are configured in a different order, the values will be sorted in ascending order after updating widget configuration in Zabbix frontend
(e.g. `"thresholds.0.threshold":"5"` → `"thresholds.0.threshold":"1"`; `"thresholds.1.threshold":"1"` → `"thresholds.1.threshold": "5"`).
:::

|Parameter|[type](/manual/api/reference/dashboard/object#dashboard-widget-field)|name|value|
|-----|-|-----|-------------------|
|*Angle*|0|angle|Possible values: 180 *(default)* or 270.|
|***Description***|<|<|<|
|*Description*|1|description|Any string value, including macros.<br>Supported macros: {HOST.\*}, {ITEM.\*}, {INVENTORY.\*}, user macros.<br><br>Default: {ITEM.NAME}.|
|*Size*|0|desc_size|Possible values range from 1-100.<br><br>Default: 15.|
|*Vertical position*|0|desc_v_pos|0 - Top;<br>1 - *(default)* Bottom.|
|*Bold*|0|desc_bold|0 - *(default)* Disabled;<br>1 - Enabled.|
|*Color*|1|desc_color|Hexadecimal color code (e.g. `FF0000`).<br><br>Default: `""` (empty).|
|***Value***|<|<|<|
|*Decimal places*|0|decimal_places|Possible values range from 1-10.<br><br>Default: 2.|
|*Size*|0|value_size|Possible values range from 1-100.<br><br>Default: 25.|
|*Bold*|0|value_bold|0 - *(default)* Disabled;<br>1 - Enabled.|
|*Color*|1|value_color|Hexadecimal color code (e.g. `FF0000`).<br><br>Default: `""` (empty).|
|***Units***|<|<|<|
|*Units* (checkbox)|0|units_show|0 - Disabled;<br>1 - *(default)* Enabled.|
|*Units* (value)|1|units|Any string value.<br><br>[Parameter behavior](/manual/api/reference_commentary#parameter-behavior):<br>- *supported* if *Units* (checkbox) is set to "Enabled"|
|*Size*|0|units_size|Possible values range from 1-100.<br><br>Default: 25.<br><br>[Parameter behavior](/manual/api/reference_commentary#parameter-behavior):<br>- *supported* if *Units* (checkbox) is set to "Enabled"|
|*Bold*|0|units_bold|0 - *(default)* Disabled;<br>1 - Enabled.<br><br>[Parameter behavior](/manual/api/reference_commentary#parameter-behavior):<br>- *supported* if *Units* (checkbox) is set to "Enabled"|
|*Position*|0|units_pos|0 - Before value;<br>1 - Above value;<br>2 - *(default)* After value;<br>3 - Below value.<br><br>[Parameter behavior](/manual/api/reference_commentary#parameter-behavior):<br>- *supported* if *Units* (checkbox) is set to "Enabled"<br><br>This parameter is ignored if set to one of the following [time-related units](/manual/config/items/item#configuration): unixtime, uptime, s.|
|*Color*|1|units_color|Hexadecimal color code (e.g. `FF0000`).<br><br>Default: `""` (empty).|
|***Value arc***|<|<|<|
|*Arc size*|0|value_arc_size|Possible values range from 1-100.<br><br>Default: 20.|
|***Needle***|<|<|<|
|*Color*|1|needle_color|Hexadecimal color code (e.g. `FF0000`).<br><br>Default: `""` (empty).<br><br>[Parameter behavior](/manual/api/reference_commentary#parameter-behavior):<br>- *supported* if a dashboard widget field object for *Show* with the value "Value arc" is set, or *Show arc* is set to "Enabled"|
|***Scale***|<|<|<|
|*Show units*|0|scale_show_units|0 - Disabled;<br>1 - *(default)* Enabled.<br><br>[Parameter behavior](/manual/api/reference_commentary#parameter-behavior):<br>- *supported* if *Units* (checkbox) is set to "Enabled" and either a dashboard widget field object for *Show* with the value "Value arc" is set, or *Show arc* is set to "Enabled"|
|*Size*|0|scale_size|Possible values range from 1-100.<br><br>Default: 15.<br><br>[Parameter behavior](/manual/api/reference_commentary#parameter-behavior):<br>- *supported* if a dashboard widget field object for *Show* with the value "Value arc" is set, or *Show arc* is set to "Enabled"|
|*Decimal places*|0|scale_decimal_places|Possible values range from 1-10.<br><br>Default: 0.<br><br>[Parameter behavior](/manual/api/reference_commentary#parameter-behavior):<br>- *supported* if a dashboard widget field object for *Show* with the value "Value arc" is set, or *Show arc* is set to "Enabled"|
|***Thresholds***|<|<|<|
|*Color*|1|thresholds.0.color|Hexadecimal color code (e.g. `FF0000`).|
|*Threshold*|1|thresholds.0.threshold|Any numeric value. [Suffixes](/manual/appendix/suffixes) (e.g. "1d", "2w", "4K", "8G") are supported.|
|*Show labels*|0|th_show_labels|0 - *(default)* Disabled;<br>1 - Enabled.<br><br>[Parameter behavior](/manual/api/reference_commentary#parameter-behavior):<br>- *supported* if *Thresholds* are set and either a dashboard widget field object for *Show* with the value "Value arc" is set or *Show arc* is set to "Enabled"|
|*Show arc*|0|th_show_arc|0 - *(default)* Disabled;<br>1 - Enabled.<br><br>[Parameter behavior](/manual/api/reference_commentary#parameter-behavior):<br>- *supported* if *Thresholds* are set|
|*Arc size*|0|th_arc_size|Possible values range from 1-100.<br><br>Default: 5.<br><br>[Parameter behavior](/manual/api/reference_commentary#parameter-behavior):<br>- *supported* if *Show arc* is set to "Enabled"|

[comment]: # ({/7886dec5-1db7caf7})

[comment]: # ({abd47a5b-f2849ab5})
### Examples

The following examples aim to only describe the configuration of the dashboard widget field objects for the *Gauge* widget.
For more information on configuring a dashboard, see [`dashboard.create`](/manual/api/reference/dashboard/create).

[comment]: # ({/abd47a5b-f2849ab5})

[comment]: # ({17a49bae-f3687306})
#### Configuring a *Gauge* widget

Configure a *Gauge* widget that displays the item value for the item "44474" (Interface enp0s3: Bits sent).
In addition, visually fine-tune the widget with multiple advanced options, including thresholds.

[Request](/manual/api#performing-requests):

```json
{
    "jsonrpc": "2.0",
    "method": "dashboard.create",
    "params": {
        "name": "My dashboard",
        "display_period": 30,
        "auto_start": 1,
        "pages": [
            {
                "widgets": [
                    {
                        "type": "gauge",
                        "name": "Gauge",
                        "x": 0,
                        "y": 0,
                        "width": 18,
                        "height": 5,
                        "view_mode": 0,
                        "fields": [
                            {
                                "type": 4,
                                "name": "itemid.0",
                                "value": 44474
                            },
                            {
                                "type": 1,
                                "name": "min",
                                "value": "100000"
                            },
                            {
                                "type": 1,
                                "name": "max",
                                "value": "1000000"
                            },
                            {
                                "type": 0,
                                "name": "show.0",
                                "value": 1
                            },
                            {
                                "type": 0,
                                "name": "show.1",
                                "value": 2
                            },
                            {
                                "type": 0,
                                "name": "show.2",
                                "value": 3
                            },
                            {
                                "type": 0,
                                "name": "show.4",
                                "value": 4
                            },
                            {
                                "type": 0,
                                "name": "show.5",
                                "value": 5
                            },
                            {
                                "type": 0,
                                "name": "angle",
                                "value": 270
                            },
                            {
                                "type": 0,
                                "name": "desc_size",
                                "value": 10
                            },
                            {
                                "type": 0,
                                "name": "desc_bold",
                                "value": 1
                            },
                            {
                                "type": 0,
                                "name": "decimal_places",
                                "value": 0
                            },
                            {
                                "type": 0,
                                "name": "value_bold",
                                "value": 1
                            },
                            {
                                "type": 0,
                                "name": "units_size",
                                "value": 15
                            },
                            {
                                "type": 0,
                                "name": "units_pos",
                                "value": 3
                            },
                            {
                                "type": 1,
                                "name": "needle_color",
                                "value": "3C3C3C"
                            },
                            {
                                "type": 1,
                                "name": "thresholds.0.color",
                                "value": "FF465C"
                            },
                            {
                                "type": 1,
                                "name": "thresholds.0.threshold",
                                "value": "700000"
                            },
                            {
                                "type": 1,
                                "name": "thresholds.1.color",
                                "value": "FFD54F"
                            },
                            {
                                "type": 1,
                                "name": "thresholds.1.threshold",
                                "value": "500000"
                            },
                            {
                                "type": 1,
                                "name": "thresholds.2.color",
                                "value": "0EC9AC"
                            },
                            {
                                "type": 1,
                                "name": "thresholds.2.threshold",
                                "value": "100000"
                            },
                            {
                                "type": 0,
                                "name": "th_show_labels",
                                "value": 1
                            },
                            {
                                "type": 0,
                                "name": "th_show_arc",
                                "value": 1
                            },
                            {
                                "type": 0,
                                "name": "th_arc_size",
                                "value": 15
                            }
                        ]
                    }
                ]
            }
        ],
        "userGroups": [
            {
                "usrgrpid": 7,
                "permission": 2
            }
        ],
        "users": [
            {
                "userid": 1,
                "permission": 3
            }
        ]
    },
    "id": 1
}
```

Response:

```json
{
    "jsonrpc": "2.0",
    "result": {
        "dashboardids": [
            "3"
        ]
    },
    "id": 1
}
```

[comment]: # ({/17a49bae-f3687306})

[comment]: # ({e9d30322-ced660a5})
### See also

-   [Dashboard widget field](/manual/api/reference/dashboard/object#dashboard-widget-field)
-   [`dashboard.create`](/manual/api/reference/dashboard/create)
-   [`dashboard.update`](/manual/api/reference/dashboard/update)

[comment]: # ({/e9d30322-ced660a5})