Gauge

Represent values within a range using an arc

npm run add Gauge

Use the Gauge component to visually represent values within a range (like speed, progress, or performance) using an arc. They are perfect for:

• At-a-glance insights: Quickly communicates status, performance, or capacity without reading detailed data.
• Improving data visualization: Makes numeric ranges more intuitive through visual scales.
• Enhancing decision-making: Helps users spot trends, thresholds, or warnings instantly.
• Engaging users: Adds a dynamic, dashboard-like feel to interfaces.

<Gauge
    percentage={72}
    value="0%"
    label="Progress"
/>

The only required prop for the Gauge component is percentage. You can however set additional labels using the value and label props. Note that the Gauge component is animated by default, meaning it’ll start count from 0% on load. Thus, when using the component with animations enabled, it’s recommended to set this to 0% for proper initial display.

Colors

You can change the colors of the gauge using the following three props:

• background: Sets the background of the gauge.
• colorFrom: Sets the starting color of the fill.
• colorTo: Sets the ending color of the fill.

<Gauge
    percentage={72}
    value="0%"
    label="Colored gauge"
    background="transparent"
    colorFrom="var(--w-color-info)"
    colorTo="var(--w-color-alert)"
/>

You can hide the background by setting it to transparent. Using two separate fill colors makes it possible to create gradients. If you need a custom solid color, simply set both colors to the same values.

Styles

The style of the gauge can be updated using the following three props:

• width: Sets the stroke width of the gauge.
• rotation: Sets a rotation to the gauge.
• rounded: Sets the edges to rounded. Defaults to true.

<Gauge
    percentage={72}
    value="0%"
    label="Styled gauge"
    width={5}
    rotation={10}
    rounded={false}
/>

Animations

By default, the component is animated. You can change animation speed using the animationSpeed prop, or turn off animation entirely by setting animated to false:

<Gauge
    percentage={72}
    value="0%"
    label="Custom animation speed"
    animationSpeed={5000} {/* Default is 2000ms */}
/>

<Gauge
    percentage={72}
    value="72%"
    label="No animation"
    animated={false} {/* Default to true */}
/>

Note that when disabling animation, you want to set value to the value of the percentage prop, as it’ll not be updated automatically.

Global Settings

The Gauge component can be customized per component call. However, if you’re dealing with multiple Gauge components on your page and you want to share styles, you can also customize the following settings globally:

html body {
    --w-gauge-width: 10;
    --w-gauge-bg: rgba(255, 255, 255, 0.2);
    --w-gauge-rotation: 0deg;
    --w-gauge-animation-speed: 2s;
}

API

type GaugeProps = {
    percentage: number
    value?: string
    label?: string
    background?: string
    colorFrom?: string
    colorTo?: string
    width?: number
    rotation?: number
    rounded?: boolean
    animationSpeed?: number
    animated?: boolean
    className?: string
}