---
layout: ~/layouts/MdxDocLayout.astro
title: "Meter"
description: "A progress/percentage meter component for displaying numeric values within a known range."
sourceFile: "components/meter"
---

import ComponentExample from "~/components/docs/ComponentExample.astro";
import ComponentSection from "~/components/docs/ComponentSection.astro";
import CodeBlock from "~/components/docs/CodeBlock.astro";
import Heading from "~/components/docs/Heading.astro";
import PropsTable from "~/components/docs/PropsTable.astro";
import {
  MeterBasicDemo,
  MeterCustomValueDemo,
  MeterHiddenValueDemo,
  MeterFullDemo,
  MeterLowDemo,
} from "~/components/demos/MeterDemo";

{/* Demo */}

<ComponentSection>
  <ComponentExample code={`<Meter label="Storage used" value={65} />`}>
    <MeterBasicDemo client:visible />
  </ComponentExample>
</ComponentSection>

{/* Installation */}

<ComponentSection>
  <Heading level={2}>Installation</Heading>
  <Heading level={3}>Barrel</Heading>
  <CodeBlock code={`import { Meter } from "@cloudflare/kumo";`} lang="tsx" />
  <Heading level={3}>Granular</Heading>
  <CodeBlock
    code={`import { Meter } from "@cloudflare/kumo/components/meter";`}
    lang="tsx"
  />
</ComponentSection>

{/* Usage */}

  <ComponentSection>
    <Heading level={2}>Usage</Heading>
    <CodeBlock
      code={`import { Meter } from "@cloudflare/kumo";

export default function Example() {
  return <Meter label="Storage used" value={65} />;
}`}
      lang="tsx"
    />
  </ComponentSection>

{/* Examples */}

  <ComponentSection>
    <Heading level={2}>Examples</Heading>

    <Heading level={3}>Basic Meter</Heading>
    <p>
      The default meter displays a label and percentage value.
    </p>
    <ComponentExample code={`<Meter label="Storage used" value={65} />`}>
      <MeterBasicDemo client:visible />
    </ComponentExample>

    <Heading level={3}>Custom Value Display</Heading>
    <p>
      Use `customValue` to show a custom
      string instead of the percentage.
    </p>
    <ComponentExample
      code={`<Meter label="API requests" value={75} customValue="750 / 1,000" />`}
    >
      <MeterCustomValueDemo client:visible />
    </ComponentExample>

    <Heading level={3}>Hidden Value</Heading>
    <p>
      Set `showValue={"{false}"}` to hide
      the value display.
    </p>
    <ComponentExample
      code={`<Meter label="Progress" value={40} showValue={false} />`}
    >
      <MeterHiddenValueDemo client:visible />
    </ComponentExample>

    <Heading level={3}>Full Meter</Heading>
    <p>A meter at 100% capacity.</p>
    <ComponentExample code={`<Meter label="Quota reached" value={100} />`}>
      <MeterFullDemo client:visible />
    </ComponentExample>

    <Heading level={3}>Low Value</Heading>
    <p>A meter with a low value.</p>
    <ComponentExample code={`<Meter label="Memory usage" value={15} />`}>
      <MeterLowDemo client:visible />
    </ComponentExample>

  </ComponentSection>

{/* API Reference */}

<ComponentSection>
  <Heading level={2}>API Reference</Heading>
  <PropsTable component="Meter" />
</ComponentSection>
