PlNumberField

A field that only holds a number. The shell is a PlTextField's to the pixel; what is added on top is a real numeric control, arrow keys, steppers, clamping and locale-aware formatting.

React

import { PlNumberField } from 'plass-ui';

<PlNumberField label="Quantity" min={1} max={12} defaultValue={2} />;
<PlNumberField label="Budget" locale="en-US" format={{ style: 'currency', currency: 'USD' }} />;

import 'package:plass_ui/plass_ui.dart';

PlNumberField(
  label: const Text('Quantity'),
  min: 1,
  max: 12,
  value: quantity,
  onChanged: (double? next) => setState(() => quantity = next),
);

PlNumberField(
  label: const Text('Budget'),
  value: budget,
  format: (double value) => '\$${value.toStringAsFixed(2)}',
  onChanged: (double? next) => setState(() => budget = next),
);

Props

Prop	Type	Default	Description
variantshared	'solid' | 'glass' | 'ghost'	'glass'	What the shell is made of, identical to PlTextField to the pixel — solid is the well cut into the sheet, not a tinted pane
sizeshared	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	Control height and type scale — the same ladder as every other field in the form
colorshared	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	Semantic colour role. Arbitrary colour values are not accepted
densityshared	'default' | 'compact'	'default'	Padding only — never the height, never the type scale
elevationshared	0 | 1 | 2 | 3	0	Drop shadow depth. 0 means no shadow at all
value	number | null	—	The number. Use with onValueChange for a controlled field
defaultValue	number	—	The initial number, for an uncontrolled field
onValueChange	(value: number | null) => void	—	Called on every change — typing, stepping, the wheel
onValueCommitted	(value: number | null) => void	—	Called when the value settles: on blur after typing, on pointer release, and together with onValueChange for the keyboard
min	number	—	The bottom of the range. Stepping stops here
max	number	—	The top of the range
step	number | 'any'	1	How far one step goes. any turns step validation off
largeStep	number	10	The step taken while Shift is held
smallStep	number	0.1	The step taken while Alt is held
snapOnStep	boolean	false	Whether stepping snaps to multiples of the step
allowWheelScrub	boolean	false	Whether the wheel changes the value while focused and hovered. Off by default: a page that scrolls under the pointer and a field that changes under it are the same gesture, and only one of them was meant
format	Intl.NumberFormatOptions	—	How the number is written — currency, percent, decimal places. Passed straight to Intl.NumberFormat, so the field shows $1,240.00 and still reports 1240
locale	Intl.LocalesArgument	—	Which locale the number is written and parsed in. Defaults to the runtime’s
steppers	'end' | 'split' | 'none'	'end'	Where the steppers sit. There is deliberately no stacked pair of half-height chevrons: at xs each arrow would be under three pixels tall, and a target that small is one nobody hits
incrementLabel	string	'Increase'	Accessible name of the increment button
decrementLabel	string	'Decrease'	Accessible name of the decrement button
label	ReactNode	—	Label above the control, wired to it by Base UI’s Field. There is no floating variant on purpose: floating labels need a transform
description	ReactNode	—	Helper text below the control
error	ReactNode	—	Error message below the control. Its presence also turns the field invalid, which re-points the whole slot family at danger
invalid	boolean	—	Forces the invalid state without a message. Defaults to !!error
startIcon	ReactNode	—	Content placed before the number — a currency mark, a unit, an icon
endIcon	ReactNode	—	Content placed after the number, before the steppers
fullWidthshared	boolean	false	Stretches to the width of the container
readOnlyshared	boolean	false	The number is shown but cannot be changed, and the steppers are not drawn
disabledshared	boolean	false	Unavailable
hotKeys	Record<string, () => void>	—	Chords this control answers to, spelled the way PlHotKeys draws them — { 'Mod+Enter': save, Escape: cancel }. A chord that matches is **consumed**
classNames	{ label?, control?, description?, error?: string }	—	Classes on the parts a className does not reach. control is the part a reader acts on

Prop	Type	Default	Description
value *	double?	—	The number. Use with onValueChange for a controlled field
onChanged	ValueChanged<double?>?	—	Called on every change — a keystroke, a step, the wheel. It reports what has been typed, not what it will settle to
onCommitted	ValueChanged<double?>?	—	Called when the value settles: on blur after typing, on pointer release, and together with onValueChange for the keyboard
min	double?	—	The bottom of the range. Stepping stops here
max	double?	—	The top of the range
step	double	1	How far one step goes. any turns step validation off
largeStep	double	10	The step taken while Shift is held
smallStep	double	0.1	The step taken while Alt is held
snapOnStep	bool	false	Whether stepping snaps to multiples of the step
allowWheelScrub	bool	false	Whether the wheel changes the value while focused and hovered. Off by default: a page that scrolls under the pointer and a field that changes under it are the same gesture, and only one of them was meant
format	String Function(double value)?	—	How a settled value is written. There is no Intl.NumberFormat in the Dart SDK, so the format is a function
parse	double? Function(String text)?	—	How typed text is read back. Left out, everything but digits, a sign and a decimal point is thrown away
steppers	PlNumberFieldSteppers	PlNumberFieldSteppers.end	Where the steppers sit. There is deliberately no stacked pair of half-height chevrons: at xs each arrow would be under three pixels tall, and a target that small is one nobody hits
incrementLabel	String	'Increase'	Accessible name of the increment button
decrementLabel	String	'Decrease'	Accessible name of the decrement button
variantshared	PlassVariant	PlassVariant.glass	What the shell is made of, identical to PlTextField to the pixel — solid is the well cut into the sheet, not a tinted pane
sizeshared	PlassSize	PlassSize.md	Control height and type scale — the same ladder as every other field in the form
colorshared	PlassColor	PlassColor.primary	Semantic colour role. Arbitrary colour values are not accepted
densityshared	PlassDensity	PlassDensity.standard	Padding only — never the height, never the type scale
elevationshared	int	0	Drop shadow depth. 0 means no shadow at all
label	Widget?	—	Label above the control. There is no floating variant on purpose: a floating label is text that moves
description	Widget?	—	Helper text below the control
error	Widget?	—	Error message below the control. Its presence also turns the field invalid, which re-points the whole slot family at danger
invalid	bool?	—	Forces the invalid state without a message. Defaults to !!error
placeholder	String?	—	Shown while the field is empty
startIcon	Widget?	—	Content placed before the number — a currency mark, a unit, an icon
endIcon	Widget?	—	Content placed after the number, before the steppers
fullWidthshared	bool	false	Stretches to the width of the container
readOnlyshared	bool	false	The number is shown but cannot be changed, and the steppers are not drawn
disabledshared	bool	false	Unavailable
semanticLabel	String?	—	The name a screen reader gives the field
focusNode	FocusNode?	—	Drive focus from outside
autofocus	bool	false	Takes focus as it is inserted into the tree
hotKeys	PlassHotKeys?	—	Chords this control answers to, spelled the way PlHotKeys draws them — { 'Mod+Enter': save, Escape: cancel }. A chord that matches is **consumed**

Every native <div> attribute passes straight through, onto the field's wrapper. color, defaultValue and children are excluded from the pass-through because all three are Plass props here.

A className lands on the stack that holds the label, the control and the two lines under it. classNames reaches the four parts inside it: label, control (the shell, steppers included) description and error.

Controlled, like every other input in the package: it is handed a value and reports what the value should become. There is no defaultValue, and value is a double?. null is an empty box.

There are two callbacks rather than one, and the difference matters here more than anywhere else in the library. onChanged fires on every keystroke with what has been typed; onCommitted fires when the field settles, with what it settled to. 5 on the way to 50 is half-finished rather than out of a range that starts at ten, so the clamp waits for the field to settle.

What the shared axes (variant size color density elevation) mean across the library is in prop conventions.

Examples

steppers

end puts both buttons at the trailing edge, the way a spinner has always looked. split puts the minus at the start and the plus at the end with the number between them, for a quantity that is nudged rather than typed. none drops them, and the field is still a number field, the arrow keys, the clamping and the formatting all stay.

There is deliberately no stacked pair of half-height chevrons. At xs each arrow would be under three pixels tall, and a target that small is a target nobody hits.

React

import { PlNumberField } from 'plass-ui';

export default function NumberFieldSteppers() {
  return (
    <div className="flex w-full max-w-md flex-col gap-4">
      <PlNumberField fullWidth label="end" defaultValue={2} />
      <PlNumberField fullWidth label="split" steppers="split" defaultValue={2} />
      <PlNumberField fullWidth label="none" steppers="none" defaultValue={2} />
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class NumberFieldSteppers extends StatefulWidget {
  const NumberFieldSteppers({super.key});

  @override
  State<NumberFieldSteppers> createState() => _NumberFieldSteppersState();
}

class _NumberFieldSteppersState extends State<NumberFieldSteppers> {
  final Map<PlNumberFieldSteppers, double?> _values = <PlNumberFieldSteppers, double?>{
    for (final steppers in PlNumberFieldSteppers.values) steppers: 2,
  };

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: 360,
      child: Column(
        mainAxisSize: MainAxisSize.min,
        spacing: 16,
        children: <Widget>[
          for (final steppers in PlNumberFieldSteppers.values)
            PlNumberField(
              fullWidth: true,
              steppers: steppers,
              label: Text(steppers.name),
              value: _values[steppers],
              onChanged: (double? next) => setState(() => _values[steppers] = next),
            ),
        ],
      ),
    );
  }
}

format

Passed straight to Intl.NumberFormat, so the field shows $1,240.00 or 18.5% while value stays a plain number. What was typed is parsed back against the same locale, which is what makes a comma mean a decimal point where it should.

Two functions rather than one options object: format writes a settled value and parse reads typed text back. There is no Intl.NumberFormat in the Dart SDK and this package has no dependencies, so a locale-aware field is one an app builds out of its own formatter, which it already has, because the rest of its screens need one too.

Left out, format writes a whole number with no decimal point and parse throws away everything but digits, a sign and a decimal point. That default pair is what makes $1,240.50 typeable into a field showing currency without either function being written.

React

import { useState } from 'react';
import { PlNumberField, PlTypography } from 'plass-ui';

export default function NumberFieldFormat() {
  const [value, setValue] = useState<number | null>(0.185);

  return (
    <div className="flex w-full max-w-md flex-col gap-4">
      <PlNumberField
        fullWidth
        label="Commission"
        value={value}
        onValueChange={setValue}
        step={0.005}
        smallStep={0.001}
        locale="en-US"
        format={{ style: 'percent', maximumFractionDigits: 2 }}
      />
      <PlTypography level="caption">
        The field shows a percentage; the value is {String(value)}.
      </PlTypography>
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class NumberFieldFormat extends StatefulWidget {
  const NumberFieldFormat({super.key});

  @override
  State<NumberFieldFormat> createState() => _NumberFieldFormatState();
}

class _NumberFieldFormatState extends State<NumberFieldFormat> {
  double? _value = 0.185;

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: 360,
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        mainAxisSize: MainAxisSize.min,
        spacing: 16,
        children: <Widget>[
          PlNumberField(
            fullWidth: true,
            label: const Text('Commission'),
            step: 0.005,
            smallStep: 0.001,
            value: _value,
            // The two halves of one idea: one writes the percentage, the other
            // reads it back into the fraction the value actually is.
            format: (double value) => '${(value * 100).toStringAsFixed(2)}%',
            parse: (String text) {
              final digits = text.replaceAll(RegExp(r'[^0-9.\-]'), '');
              final percent = double.tryParse(digits);

              return percent == null ? null : percent / 100;
            },
            onChanged: (double? next) => setState(() => _value = next),
          ),
          PlTypography(
            'The field shows a percentage; the value is $_value.',
            level: PlTypographyLevel.caption,
          ),
        ],
      ),
    );
  }
}

step, largeStep and smallStep

The arrow keys and the steppers both move by step, with Shift taking largeStep and Alt taking smallStep, the modifiers count for a pressed stepper as well as a pressed key. snapOnStep makes a step land on a multiple rather than move by one.

Page Up and Page Down take largeStep too, and Home and End go to min and max when there are any. A stepper held down repeats after a short pause; a stepper pressed and let go is worth exactly one step, the way every other button in the library is.

React

import { PlNumberField } from 'plass-ui';

export default function NumberFieldSteps() {
  return (
    <div className="flex w-full max-w-md flex-col gap-4">
      <PlNumberField
        fullWidth
        label="Hold Shift for 10, Alt for 0.1"
        description="Arrow keys and the steppers both take the modifiers."
        defaultValue={0}
        largeStep={10}
        smallStep={0.1}
      />
      <PlNumberField
        fullWidth
        label="Snapped to multiples of 5"
        defaultValue={7}
        step={5}
        snapOnStep
      />
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class NumberFieldSteps extends StatefulWidget {
  const NumberFieldSteps({super.key});

  @override
  State<NumberFieldSteps> createState() => _NumberFieldStepsState();
}

class _NumberFieldStepsState extends State<NumberFieldSteps> {
  double? _modifiers = 0;
  double? _snapped = 7;

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: 360,
      child: Column(
        mainAxisSize: MainAxisSize.min,
        spacing: 16,
        children: <Widget>[
          PlNumberField(
            fullWidth: true,
            label: const Text('Hold Shift for 10, Alt for 0.1'),
            description: const Text('The arrow keys and the steppers both take the modifiers.'),
            largeStep: 10,
            smallStep: 0.1,
            value: _modifiers,
            onChanged: (double? next) => setState(() => _modifiers = next),
          ),
          PlNumberField(
            fullWidth: true,
            label: const Text('Snapped to multiples of 5'),
            step: 5,
            snapOnStep: true,
            value: _snapped,
            onChanged: (double? next) => setState(() => _snapped = next),
          ),
        ],
      ),
    );
  }
}

variant

The shell is a PlTextField's, to the pixel. A form where the quantity box is a different height or radius from the boxes around it is a form that looks assembled rather than designed, so solid is the well cut into the sheet here too, not a tinted pane.

React

import { PlNumberField } from 'plass-ui';

export default function NumberFieldVariants() {
  return (
    <div className="flex w-full max-w-md flex-col gap-4">
      {(['solid', 'glass', 'ghost'] as const).map((variant) => (
        <PlNumberField key={variant} fullWidth variant={variant} label={variant} defaultValue={8} />
      ))}
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class NumberFieldVariants extends StatefulWidget {
  const NumberFieldVariants({super.key});

  @override
  State<NumberFieldVariants> createState() => _NumberFieldVariantsState();
}

class _NumberFieldVariantsState extends State<NumberFieldVariants> {
  final Map<PlassVariant, double?> _values = <PlassVariant, double?>{
    for (final variant in PlassVariant.values) variant: 8,
  };

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: 360,
      child: Column(
        mainAxisSize: MainAxisSize.min,
        spacing: 16,
        children: <Widget>[
          for (final variant in PlassVariant.values)
            PlNumberField(
              fullWidth: true,
              variant: variant,
              label: Text(variant.name),
              value: _values[variant],
              onChanged: (double? next) => setState(() => _values[variant] = next),
            ),
        ],
      ),
    );
  }
}

States

readOnly keeps the number readable and takes the steppers away; there is nothing to press on a value that cannot change. error also turns the field invalid, which re-points the whole slot family at danger, so the edge, the ring, the caret and the message all turn over together.

React

import { PlNumberField } from 'plass-ui';

export default function NumberFieldStates() {
  return (
    <div className="flex w-full max-w-md flex-col gap-4">
      <PlNumberField fullWidth label="Read-only" readOnly value={12} />
      <PlNumberField fullWidth label="Disabled" disabled defaultValue={12} />
      <PlNumberField fullWidth label="With an error" defaultValue={99} error="Twelve at most." />
      <PlNumberField
        fullWidth
        label="With a unit"
        defaultValue={3}
        endIcon={<span className="text-xs">kg</span>}
      />
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class NumberFieldStates extends StatefulWidget {
  const NumberFieldStates({super.key});

  @override
  State<NumberFieldStates> createState() => _NumberFieldStatesState();
}

class _NumberFieldStatesState extends State<NumberFieldStates> {
  double? _error = 99;
  double? _unit = 3;

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: 360,
      child: Column(
        mainAxisSize: MainAxisSize.min,
        spacing: 16,
        children: <Widget>[
          const PlNumberField(fullWidth: true, label: Text('Read-only'), readOnly: true, value: 12),
          const PlNumberField(fullWidth: true, label: Text('Disabled'), disabled: true, value: 12),
          PlNumberField(
            fullWidth: true,
            label: const Text('With an error'),
            error: const Text('Twelve at most.'),
            value: _error,
            onChanged: (double? next) => setState(() => _error = next),
          ),
          PlNumberField(
            fullWidth: true,
            label: const Text('With a unit'),
            endIcon: const Text('kg'),
            value: _unit,
            onChanged: (double? next) => setState(() => _unit = next),
          ),
        ],
      ),
    );
  }
}

size

React

import { PlNumberField } from 'plass-ui';

export default function NumberFieldSizes() {
  return (
    <div className="flex w-full max-w-md flex-col gap-4">
      {(['xs', 'sm', 'md', 'lg', 'xl'] as const).map((size) => (
        <PlNumberField key={size} fullWidth size={size} label={size} defaultValue={12} />
      ))}
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class NumberFieldSizes extends StatefulWidget {
  const NumberFieldSizes({super.key});

  @override
  State<NumberFieldSizes> createState() => _NumberFieldSizesState();
}

class _NumberFieldSizesState extends State<NumberFieldSizes> {
  final Map<PlassSize, double?> _values = <PlassSize, double?>{
    for (final size in PlassSize.values) size: 12,
  };

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: 360,
      child: Column(
        mainAxisSize: MainAxisSize.min,
        spacing: 16,
        children: <Widget>[
          for (final size in PlassSize.values)
            PlNumberField(
              fullWidth: true,
              size: size,
              label: Text(size.name),
              value: _values[size],
              onChanged: (double? next) => setState(() => _values[size] = next),
            ),
        ],
      ),
    );
  }
}

Accessibility

• Base UI's NumberField owns the hard parts: parsing what was typed against the locale, clamping to min/max, the press-and-hold repeat on the steppers, and the hidden input that submits with a form.
• The label, the description and the error are wired to the control by Base UI's Field, so none of them needs an id from the caller.
• Both steppers carry an accessible name already; incrementLabel and decrementLabel are what change them.
• A stepper that has run into the end of the range is genuinely disabled, not just dimmed.
• allowWheelScrub is off by default. A page that scrolls under the pointer and a field that changes under it are the same gesture, and only one of them was meant.

• The field is announced as a text field holding what it shows, so a screen reader reads $1,240.00 rather than 1240. What is drawn is what is read.
• Both steppers carry a name already; incrementLabel and decrementLabel are what change them. Each is its own focus stop, after the number.
• A stepper that has run into the end of the range is announced as unavailable, not merely dimmed.
• The arrow keys are bound inside the field, closer to the editor than an app's own text-editing shortcuts, which is what keeps the up arrow moving the number rather than the caret.
• allowWheelScrub is off by default, and even on it wants the field focused and the pointer over it. A page that scrolls under the pointer and a field that changes under it are the same gesture, and only one of them was meant.
• The label, the description and the error are part of the component, so there is no id to wire and nothing to forget to wire.

Differences from the React build

React	Flutter	Why
value / defaultValue / onValueChange	value / onChanged	Flutter's own controls are controlled, and its name for the callback.
onValueCommitted	onCommitted	Same idea, shorter name, and it is where the clamp happens.
format, an Intl.NumberFormatOptions	format and parse, two functions	There is no Intl.NumberFormat in the Dart SDK and this package has no dependencies. A field that formats without parsing cannot be typed into, so both halves are the caller's.
locale	—	It belongs to the formatter the app passes in, which already knows which locale it is writing.
a value of number | null	double?	Dart's floating-point type. An int field is step: 1 with a format that writes no decimals.
the hidden input, name, required	—	There is no native form submission to be part of.
id	—	Nothing points at anything by id here; the label and the messages are part of the component.
className, style, native attributes	—	There is no class list and no style attribute to pass through.