# Meter

Displays numeric value that varies within a defined range

## Import

```
Copyts
import { Meter } from "@kobalte/core/meter";
// or
import { Root, Label, ... } from "@kobalte/core/meter";
```

```
Copyts
import { Meter } from "@kobalte/core/meter";
// or
import { Root, Label, ... } from "@kobalte/core/meter";
```

## Features

- Exposed to assistive technology as a meter via ARIA.
- Labeling support for accessibility.
- Internationalized number formatting as a percentage or value.

## Anatomy

The meter consists of:

- **Meter:** The root container for a meter.
- **Meter.Label:** An accessible label that gives the user information on the meter.
- **Meter.ValueLabel:** The accessible label text representing the current value in a human-readable format.
- **Meter.Track:** The component that visually represents the meter track.
- **Meter.Fill:** The component that visually represents the meter value.

```
Copytsx
<Meter>
	<Meter.Label />
	<Meter.ValueLabel />
	<Meter.Track>
		<Meter.Fill />
	</Meter.Track>
</Meter>
```

```
Copytsx
<Meter>
	<Meter.Label />
	<Meter.ValueLabel />
	<Meter.Track>
		<Meter.Fill />
	</Meter.Track>
</Meter>
```

## Example

Battery Level:

80%

index.tsxstyle.css

```
Copytsx
import { Meter } from "@kobalte/core/meter";
import "./style.css";

function App() {
  return (
    <Meter value={80} class="meter">
      <div class="meter__label-container">
        <Meter.Label class="meter__label">Battery Level:</Meter.Label>
        <Meter.ValueLabel class="meter__value-label" />
      </div>
      <Meter.Track class="meter__track">
        <Meter.Fill class="meter__fill" />
      </Meter.Track>
    </Meter>
  );
}
```

```
Copytsx
import { Meter } from "@kobalte/core/meter";
import "./style.css";

function App() {
  return (
    <Meter value={80} class="meter">
      <div class="meter__label-container">
        <Meter.Label class="meter__label">Battery Level:</Meter.Label>
        <Meter.ValueLabel class="meter__value-label" />
      </div>
      <Meter.Track class="meter__track">
        <Meter.Fill class="meter__fill" />
      </Meter.Track>
    </Meter>
  );
}
```

## Usage

### Custom value scale

By default, the `value` prop represents the current value of meter, as the minimum and maximum values default to 0 and 100, respectively. Alternatively, a different scale can be used by setting the `minValue` and `maxValue` props.

Disk Space Usage:

40%

```
Copytsx
<Meter value={100} minValue={0} maxValue={250} class="meter">
	<div class="meter__label-container">
		<Meter.Label class="meter__label">Disk Space Usage:</Meter.Label>
		<Meter.ValueLabel class="meter__value-label" />
	</div>
	<Meter.Track class="meter__track">
		<Meter.Fill class="meter__fill" />
	</Meter.Track>
</Meter>
```

```
Copytsx
<Meter value={100} minValue={0} maxValue={250} class="meter">
	<div class="meter__label-container">
		<Meter.Label class="meter__label">Disk Space Usage:</Meter.Label>
		<Meter.ValueLabel class="meter__value-label" />
	</div>
	<Meter.Track class="meter__track">
		<Meter.Fill class="meter__fill" />
	</Meter.Track>
</Meter>
```

### Custom value label

The `getValueLabel` prop allows the formatted value used in `Meter.ValueLabel` and ARIA to be replaced with a custom string. It receives the current value, min and max values as parameters.

Processing...

3 of 10 tasks completed

```
Copytsx
<Meter
	value={3}
	minValue={0}
	maxValue={10}
	getValueLabel={({ value, max }) => `${value} of ${max} tasks completed`}
	class="meter"
>
	<div class="meter__label-container">
		<Meter.Label class="meter__label">Processing...</Meter.Label>
		<Meter.ValueLabel class="meter__value-label" />
	</div>
	<Meter.Track class="meter__track">
		<Meter.Fill class="meter__fill" />
	</Meter.Track>
</Meter>
```

```
Copytsx
<Meter
	value={3}
	minValue={0}
	maxValue={10}
	getValueLabel={({ value, max }) => `${value} of ${max} tasks completed`}
	class="meter"
>
	<div class="meter__label-container">
		<Meter.Label class="meter__label">Processing...</Meter.Label>
		<Meter.ValueLabel class="meter__value-label" />
	</div>
	<Meter.Track class="meter__track">
		<Meter.Fill class="meter__fill" />
	</Meter.Track>
</Meter>
```

### Meter fill width

We expose a CSS custom property `--kb-meter-fill-width` which corresponds to the percentage of meterion (ex: 80%). If you are building a linear meter, you can use it to set the width of the `Meter.Fill` component in CSS.

## API Reference

### Meter

`Meter` is equivalent to the `Root` import from `@kobalte/core/meter`.

| Prop | Description |
| --- | --- |
| value | `number`<br> The meter value. |
| minValue | `number`<br> The minimum meter value. |
| maxValue | `number`<br> The maximum meter value. |
| getValueLabel | `(params: { value: number; min: number; max: number }) => string`<br> A function to get the accessible label text representing the current value in a human-readable format. If not provided, the value label will be read as a percentage of the max value. |

| Data attribute | Description |
| --- | --- |

`Meter.Label`, `Meter.ValueLabel`, `Meter.Track` and `Meter.Fill` shares the same data-attributes.

## Rendered elements

| Component | Default rendered element |
| --- | --- |
| `Meter` | `div` |
| `Meter.Label` | `span` |
| `Meter.ValueLabel` | `div` |
| `Meter.Track` | `div` |
| `Meter.Fill` | `div` |

Previous[←Menubar](https://kobalte.dev/docs/core/components/menubar)Next[Navigation Menu→](https://kobalte.dev/docs/core/components/navigation-menu)