Percent Field

The Percent Field component provides a percentage input that automatically converts between stored decimal values (0-1) and displayed percentage values (0-100).

Basic Usage

With Precision

Required Field

Read-Only

Field Schema

A percent field is authored as PercentFieldMetadata (@object-ui/types), which is the source of truth for the key set: it extends BaseFieldMetadata with the decimal precision and the two bounds.

import type { PercentFieldMetadata } from '@object-ui/types';

const discountRate: PercentFieldMetadata = {
  type: 'percent',
  name: 'discount_rate',
  label: 'Discount Rate',
  placeholder: '0%',
  precision: 2,
  min: 0,
  max: 1,
};

The value being edited, and the className / disabled a host supplies, are not metadata keys — they are runtime widget props. See Field Widget Props.

What the browser rewrites before this field sees it

This widget renders a native type="number" input, so the browser decides what the box accepts. Two things can happen and only one of them is announced:

• Announced. Text the browser cannot read at all — 1e, a lone -, a lone . — leaves the box visibly showing what was typed while its value reads empty. The field is marked aria-invalid and draws "Not saved: the text in this box is not a number."
• ⚠️ Not announced. Entries the browser silently truncates: pasting 1.2.3 stores 0.0123, and 0x10 stores 0.1. No warning is possible here — the browser discards the extra characters as they arrive, so nothing reaches ObjectUI to check.

⛔ "No warning" therefore does not mean "the value is right." Full explanation and the reasoning: What a number field silently rewrites.

Value Conversion

The percent field handles automatic conversion:

• Stored Value: Decimal between 0 and 1 (e.g., 0.75)
• Display Value: Percentage between 0 and 100 (e.g., 75%)

Example:

// Stored in database: 0.85
// Displayed to user: 85%
// User enters: 90
// Stored as: 0.90

Cell Renderer

In tables/grids, values are formatted with percentage symbol:

import { PercentCellRenderer } from '@object-ui/fields';

// Renders: 85.50%

Use Cases

• Progress Tracking: Task completion, project progress
• Analytics: Conversion rates, success metrics
• Financial Data: Interest rates, discount percentages
• Statistics: Performance scores, efficiency ratings