class="meter-track" aria-hidden="true" │ │
│ │
class="meter-fill" style="width: 75%" │ │
│ └─────────────────────────────────────────────────────┘ │
│ class="meter-value" aria-hidden="true">75%│
└─────────────────────────────────────────────────────────┘
```
### Value Clamping
```typescript
const clampNumber = (value: number, min: number, max: number, clamp: boolean) => {
if (!Number.isFinite(value) || !Number.isFinite(min) || !Number.isFinite(max)) {
return value; // Let validation handle non-finite
}
return clamp ? Math.min(max, Math.max(min, value)) : value;
};
```
### Format Prop
The `format` prop accepts a string pattern for displaying values. Available placeholders:
- `{value}` - Current value
- `{min}` - Minimum value
- `{max}` - Maximum value
```typescript
// Examples
// "75%"
// "3 of 5"
```
### Common Pitfalls
1. **Missing accessible name**: Always require label, aria-label, or aria-labelledby
2. **Conflicting props**: Use TypeScript exclusive types to prevent aria-valuenow override via rest props
3. **Visual-ARIA mismatch**: Ensure visual bar width matches aria-valuenow percentage
4. **Non-finite values**: Validate and warn on NaN/Infinity
## Example Test Code (React + Testing Library)
```typescript
import { render, screen } from '@testing-library/react';
import { axe, toHaveNoViolations } from 'jest-axe';
expect.extend(toHaveNoViolations);
// Role test
it('has role="meter"', () => {
render();
expect(screen.getByRole('meter')).toBeInTheDocument();
});
// ARIA values test
it('has correct aria-valuenow/min/max', () => {
render();
const meter = screen.getByRole('meter');
expect(meter).toHaveAttribute('aria-valuenow', '75');
expect(meter).toHaveAttribute('aria-valuemin', '0');
expect(meter).toHaveAttribute('aria-valuemax', '100');
});
// Clamping test
it('clamps value to min/max range', () => {
render();
expect(screen.getByRole('meter')).toHaveAttribute('aria-valuenow', '100');
});
// aria-valuetext test
it('sets aria-valuetext when valueText provided', () => {
render();
expect(screen.getByRole('meter')).toHaveAttribute('aria-valuetext', '75 percent');
});
// format test
it('uses format for aria-valuetext', () => {
render();
expect(screen.getByRole('meter')).toHaveAttribute('aria-valuetext', '75%');
});
// Not focusable by default
it('is not focusable by default', () => {
render();
expect(screen.getByRole('meter')).not.toHaveAttribute('tabindex');
});
// axe test
it('has no axe violations', async () => {
const { container } = render();
const results = await axe(container);
expect(results).toHaveNoViolations();
});
// Negative range test
it('handles negative min/max range', () => {
render();
const meter = screen.getByRole('meter');
expect(meter).toHaveAttribute('aria-valuenow', '0');
expect(meter).toHaveAttribute('aria-valuemin', '-50');
expect(meter).toHaveAttribute('aria-valuemax', '50');
});
```
## Example E2E Test Code (Playwright)
```typescript
import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';
test.beforeEach(async ({ page }) => {
await page.goto('patterns/meter/react/');
await page.waitForLoadState('networkidle');
});
// ARIA structure test
test('has correct ARIA attributes', async ({ page }) => {
const meters = page.locator('[role="meter"]');
const count = await meters.count();
expect(count).toBeGreaterThan(0);
for (let i = 0; i < count; i++) {
const meter = meters.nth(i);
// Required attributes
const valueNow = await meter.getAttribute('aria-valuenow');
const valueMin = await meter.getAttribute('aria-valuemin');
const valueMax = await meter.getAttribute('aria-valuemax');
expect(valueNow).not.toBeNull();
expect(valueMin).not.toBeNull();
expect(valueMax).not.toBeNull();
// Value should be within range
expect(Number(valueNow)).toBeGreaterThanOrEqual(Number(valueMin));
expect(Number(valueNow)).toBeLessThanOrEqual(Number(valueMax));
// Must have accessible name
const ariaLabel = await meter.getAttribute('aria-label');
const ariaLabelledby = await meter.getAttribute('aria-labelledby');
expect(ariaLabel !== null || ariaLabelledby !== null).toBe(true);
}
});
// Non-interactive behavior test
test('is not focusable by default', async ({ page }) => {
const meters = page.locator('[role="meter"]');
const count = await meters.count();
for (let i = 0; i < count; i++) {
const meter = meters.nth(i);
const tabindex = await meter.getAttribute('tabindex');
// Should not have tabindex, or if present should be -1
if (tabindex !== null) {
expect(Number(tabindex)).toBe(-1);
}
}
});
// Accessibility test
test('has no axe-core violations', async ({ page }) => {
await page.locator('[role="meter"]').first().waitFor();
const results = await new AxeBuilder({ page }).include('[role="meter"]').analyze();
expect(results.violations).toEqual([]);
});
```