# Meter

Meters visually represent a quantity or achievement, displaying progress on a bar with a label.

## Example

```python
from deephaven import ui


@ui.component
def ui_meter():
    return ui.meter(label="RAM Usage", value=35)


my_meter = ui_meter()
```

## Value

The `value` prop controls the meter and represents the current percentage of progress. By default, the minimum and maximum values are 0 and 100 but a different scale can be used by setting the `min_value` and `max_value` props.

```python
from deephaven import ui


@ui.component
def ui_meter_value():
    return ui.meter(label="Tutorials completed", value=100, min_value=50, max_value=150)


my_meter_value = ui_meter_value()
```

## Formatting

The `format_options` prop dictates how the value is displayed and which characters can be inputted. This parameter supports three styles: Percentage, Currency, and Units.

Note: This prop is compatible with the option parameter of [Intl.NumberFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat).

```python
from deephaven import ui


@ui.component
def ui_meter_format():
    return ui.meter(
        label="Currency",
        value=75,
        format_options={"style": "currency", "currency": "USD"},
    )


my_meter_format = ui_meter_format()
```

## Labeling

When a label is provided, value labels are positioned above the meter by default. The `label_position` prop can change where these labels are placed, while the `show_value_prop` can hide them entirely.

```python
from deephaven import ui


@ui.component
def ui_meter_label():
    return [
        ui.meter(
            label="Label",
            value=50,
        ),
        ui.meter(
            label="Label",
            value=50,
            label_position="side",
        ),
        ui.meter(label="Label", value=50, show_value_label=False),
    ]


my_meter_label = ui_meter_label()
```

The `value_label` prop can update the value label directly where showing a different scale makes sense.

```python
from deephaven import ui


@ui.component
def ui_meter_value_label():
    return ui.meter(label="Currency", value=20, value_label="1 of 5")


my_meter_value_label = ui_meter_value_label()
```

## Size

The `size` prop controls how thick the meter bar is displayed.

```python
from deephaven import ui


@ui.component
def ui_meter_size():
    return [
        ui.meter(label="Progress", value=75, size="S"),
        ui.meter(label="Progress", value=75, size="L"),
    ]


my_meter_size = ui_meter_size()
```

## Variants

The `variant` prop changes the meter’s visual style. It supports four options: informative, positive, critical, and warning.

```python
from deephaven import ui


@ui.component
def ui_meter_variant():
    return [
        ui.meter(
            label="Progress",
            value=75,
            variant="informative",
        ),
        ui.meter(
            label="Progress",
            value=75,
            variant="positive",
        ),
        ui.meter(
            label="Progress",
            value=75,
            variant="critical",
        ),
        ui.meter(
            label="Progress",
            value=75,
            variant="warning",
        ),
    ]


my_meter_variant = ui_meter_variant()
```

## API Reference

Meters visually represent a quantity or achievement, displaying progress on a bar with a label.

**Returns:** `Element` The rendered meter element.

<ParamTable param={{"module_name": "deephaven.ui.", "name": "meter", "parameters": [{"name": "variant", "type": "Literal['informative', 'positive', 'critical', 'warning']", "description": "The visual style of the meter.", "default": "'informative'"}, {"name": "size", "type": "Literal['S', 'L']", "description": "How thick the bar should be.", "default": "'L'"}, {"name": "label_position", "type": "Literal['top', 'side']", "description": "The position of the label relative to the input.", "default": "'top'"}, {"name": "show_value_label", "type": "bool | None", "description": "Whether to show the value label.", "default": "None"}, {"name": "label", "type": "Any | None", "description": "The label for the input.", "default": "None"}, {"name": "format_options", "type": "NumberFormatOptions | None", "description": "Options for formatting the displayed value, which also restricts input characters.", "default": "None"}, {"name": "value_label", "type": "Any | None", "description": "The label for the value (e.g. 1 of 4).", "default": "None"}, {"name": "value", "type": "float", "description": "The current value of the input", "default": "0"}, {"name": "min_value", "type": "float", "description": "The minimum value of the input", "default": "0"}, {"name": "max_value", "type": "float", "description": "The maximum value of the input", "default": "100"}, {"name": "flex", "type": "str | float | bool | None", "description": "When used in a flex layout, specifies how the element will grow or shrink to fit the space available.", "default": "None"}, {"name": "flex_grow", "type": "float | None", "description": "When used in a flex layout, specifies how the element will grow to fit the space available.", "default": "None"}, {"name": "flex_shrink", "type": "float | None", "description": "When used in a flex layout, specifies how the element will shrink to fit the space available.", "default": "None"}, {"name": "flex_basis", "type": "str | float | None", "description": "When used in a flex layout, specifies the initial main size of the element.", "default": "None"}, {"name": "align_self", "type": "Literal['auto', 'normal', 'start', 'end', 'center', 'flex-start', 'flex-end', 'self-start', 'self-end', 'stretch'] | None", "description": "Overrides the alignItems property of a flex or grid container.", "default": "None"}, {"name": "justify_self", "type": "Literal['auto', 'normal', 'start', 'end', 'flex-start', 'flex-end', 'self-start', 'self-end', 'center', 'left', 'right', 'stretch'] | None", "description": "Species how the element is justified inside a flex or grid container.", "default": "None"}, {"name": "order", "type": "int | None", "description": "The layout order for the element within a flex or grid container.", "default": "None"}, {"name": "grid_area", "type": "str | None", "description": "When used in a grid layout specifies, specifies the named grid area that the element should be placed in within the grid.", "default": "None"}, {"name": "grid_row", "type": "str | None", "description": "When used in a grid layout, specifies the row the element should be placed in within the grid.", "default": "None"}, {"name": "grid_column", "type": "str | None", "description": "When used in a grid layout, specifies the column the element should be placed in within the grid.", "default": "None"}, {"name": "grid_row_start", "type": "str | None", "description": "When used in a grid layout, specifies the starting row to span within the grid.", "default": "None"}, {"name": "grid_row_end", "type": "str | None", "description": "When used in a grid layout, specifies the ending row to span within the grid.", "default": "None"}, {"name": "grid_column_start", "type": "str | None", "description": "When used in a grid layout, specifies the starting column to span within the grid.", "default": "None"}, {"name": "grid_column_end", "type": "str | None", "description": "When used in a grid layout, specifies the ending column to span within the grid.", "default": "None"}, {"name": "margin", "type": "str | float | None", "description": "The margin for all four sides of the element.", "default": "None"}, {"name": "margin_top", "type": "str | float | None", "description": "The margin for the top side of the element.", "default": "None"}, {"name": "margin_bottom", "type": "str | float | None", "description": "The margin for the bottom side of the element.", "default": "None"}, {"name": "margin_start", "type": "str | float | None", "description": "The margin for the logical start side of the element, depending on layout direction.", "default": "None"}, {"name": "margin_end", "type": "str | float | None", "description": "The margin for the logical end side of the element, depending on layout direction.", "default": "None"}, {"name": "margin_x", "type": "str | float | None", "description": "The margin for the left and right sides of the element.", "default": "None"}, {"name": "margin_y", "type": "str | float | None", "description": "The margin for the top and bottom sides of the element.", "default": "None"}, {"name": "width", "type": "str | float | None", "description": "The width of the element.", "default": "None"}, {"name": "min_width", "type": "str | float | None", "description": "The minimum width of the element.", "default": "None"}, {"name": "max_width", "type": "str | float | None", "description": "The maximum width of the element.", "default": "None"}, {"name": "height", "type": "str | float | None", "description": "The height of the element.", "default": "None"}, {"name": "min_height", "type": "str | float | None", "description": "The minimum height of the element.", "default": "None"}, {"name": "max_height", "type": "str | float | None", "description": "The maximum height of the element.", "default": "None"}, {"name": "position", "type": "Literal['static', 'relative', 'absolute', 'fixed', 'sticky'] | None", "description": "The position of the element.", "default": "None"}, {"name": "top", "type": "str | float | None", "description": "The distance from the top of the containing element.", "default": "None"}, {"name": "bottom", "type": "str | float | None", "description": "The distance from the bottom of the containing element.", "default": "None"}, {"name": "left", "type": "str | float | None", "description": "The distance from the left of the containing element.", "default": "None"}, {"name": "right", "type": "str | float | None", "description": "The distance from the right of the containing element.", "default": "None"}, {"name": "start", "type": "str | float | None", "description": "The distance from the start of the containing element, depending on layout direction.", "default": "None"}, {"name": "end", "type": "str | float | None", "description": "The distance from the end of the containing element, depending on layout direction.", "default": "None"}, {"name": "z_index", "type": "int | None", "description": "The stack order of the element.", "default": "None"}, {"name": "is_hidden", "type": "bool | None", "description": "Whether the element is hidden.", "default": "None"}, {"name": "id", "type": "str | None", "description": "The unique identifier of the element.", "default": "None"}, {"name": "aria_label", "type": "str | None", "description": "The label for the element.", "default": "None"}, {"name": "aria_labelledby", "type": "str | None", "description": "The id of the element that labels the current element.", "default": "None"}, {"name": "aria_describedby", "type": "str | None", "description": "The id of the element that describes the current element.", "default": "None"}, {"name": "aria_details", "type": "str | None", "description": "The id of the element that provides additional information about the current element.", "default": "None"}, {"name": "UNSAFE_class_name", "type": "str | None", "description": "A CSS class to apply to the element.", "default": "None"}, {"name": "UNSAFE_style", "type": "Dict[str, Any] | None", "description": "A CSS style to apply to the element.", "default": "None"}, {"name": "key", "type": "str | None", "description": "A unique identifier used by React to render elements in a list.", "default": "None"}]}} />