Skip to content
BigBang

Popular

    ↑↓Navigate↵OpenEscClose
    TR

    Components

    Meter

    Shows one value in a known range as a bar: storage used, a quota, a score.

    Storybook
    Storybook
    Source
    Source

    Installation

    Section titled “Installation”
    Package
    @bigbang/ui
    Import
    import { Meter } from '@bigbang/ui';
    Source
    Meter.tsx
    Storybook
    Meter · Playground

    Meter is in the @bigbang/ui package. Installation and style files are the same as for Button; see the Button code tab.

    import { Meter } from '@bigbang/ui';
    

    <Meter label="Storage" value={64} />;

    Props

    Section titled “Props”
    labelRequired
    Description
    What is measured, such as "Storage". It names the meter.
    Type
    ReactNode
    labelHidden
    Description
    Hides the label visually; it still names the meter for screen readers. Use it when the surrounding text already says what is measured.
    Type
    boolean
    Default
    false
    valueRequired
    Description
    The measured value, between min and max. A value outside the range is drawn at the nearest end.
    Type
    number
    min
    Description
    The start of the range.
    Type
    number
    Default
    0
    max
    Description
    The end of the range.
    Type
    number
    Default
    100
    format
    Description
    Intl.NumberFormat options for the shown and read value, such as { style: 'unit', unit: 'gigabyte' }. Without it the value is shown as a percent of the range.
    Type
    NumberFormatOptions
    showValue
    Description
    Shows the formatted value next to the label. Screen readers read the value text either way.
    Type
    boolean
    Default
    true
    valueText
    Description
    Replaces the text screen readers read for the value, such as "12 of 50 gigabytes used". It also replaces the word added under tone="auto".
    Type
    string
    description
    Description
    Helper text under the bar, linked to the meter with aria-describedby.
    Type
    ReactNode
    size
    Description
    Track height: 4 or 8 px. Use sm in dense rows and tables.
    Type
    'sm' | 'md'
    Default
    'md'
    tone
    Description
    Fill colour. auto follows the HTML meter regions from low, high and optimum and adds a word to the value text; without any of them it is brand. The other tones are fixed.
    Type
    'auto' | ResolvedTone
    Default
    'auto'
    low
    Description
    Upper end of the low region (inclusive), for tone="auto". Defaults to min.
    Type
    number
    high
    Description
    Lower end of the high region (inclusive), for tone="auto". Defaults to max.
    Type
    number
    optimum
    Description
    The best value, for tone="auto". The region that holds it is good, its neighbour is a warning, the far one is danger. Defaults to the middle of the range.
    Type
    number
    className
    Description
    For layout only: margins and width. Do not use it to change colour or height.
    Type
    string

    Native attributes (id, aria-*) pass through to the root element.

    Data attributes

    Section titled “Data attributes”
    • data-component="meter", data-size, data-tone: on the root. data-tone holds the colour auto resolved to.
    • data-part: label, value, track, indicator, description.

    Unit and thresholds

    Section titled “Unit and thresholds”
    <Meter
      label="Quota used"
      value={32}
      max={50}
      format={{ style: 'unit', unit: 'gigabyte' }}
      low={25}
      high={40}
      optimum={0}
    />