NumberField | Dashforge-UI
Dashforge-UI
DocsStarter Kits
v0.1.0-alpha

NumberField

A specialized numeric input component built on MUI TextField. Provides built-in parsing (controlled value is number | null, never NaN), min/max constraints, and step increments. Supports standalone usage and seamless DashForm integration with automatic field binding and validation. Includes reactive visibility for conditional rendering.

Quick Start

Copy & Paste

import { NumberField } from '@dashforge/ui';

<NumberField label="Price" name="price" />

Examples

Common NumberField patterns and numeric input configurations

Basic

A simple numeric input field

<NumberField label="Quantity" name="quantity" />
Min / Max

Constrained numeric input with boundaries

<NumberField
  label="Age"
  name="age"
  inputProps={{ min: 0, max: 120 }}
/>
Step Increments

Numeric field with defined step intervals

<NumberField
  label="Price"
  name="price"
  inputProps={{ step: 0.01 }}
/>
Decimals

Support for decimal values with precision

0-100

<NumberField
  label="Discount %"
  name="discount"
  helperText="0-100"
  inputProps={{ min: 0, max: 100, step: 0.1 }}
/>
Disabled

A disabled numeric field

<NumberField
  label="Locked Value"
  name="locked"
  value={100}
  disabled
/>
Error State

A numeric field displaying an error

Value must be positive

<NumberField
  label="Amount"
  name="amount"
  error
  helperText="Value must be positive"
/>
Full Width

A numeric field that spans the full width of its container

<NumberField
  label="Revenue"
  name="revenue"
  fullWidth
/>

Layout Variants

Floating, stacked, and inline label layouts

NumberField supports three MUI variants: outlined (default), filled, and standard. The variant prop controls the visual style of the input field, maintaining consistency with MUI design patterns.

Outlined (Default)
Live Preview

Enter amount in USD

<NumberField
  label="Price"
  name="price"
  placeholder="0.00"
  helperText="Enter amount in USD"
  fullWidth
/>

What to observe: Standard outlined border style. Label animates up when field is focused or has value. Most common variant for forms.

Filled Variant
Live Preview

Enter amount in USD

<NumberField
  label="Price"
  name="price"
  placeholder="0.00"
  helperText="Enter amount in USD"
  variant="filled"
  fullWidth
/>

What to observe: Background-filled style with bottom border. Provides visual weight and clear input area. Helper text appears below.

Standard Variant
Live Preview

Enter amount in USD

<NumberField
  label="Price"
  name="price"
  placeholder="0.00"
  helperText="Enter amount in USD"
  variant="standard"
  fullWidth
/>

What to observe: Minimal style with only bottom border. Clean, simple appearance for focused forms. Label floats above on focus.

Interactive Playground

Experiment with numeric input props and see live results

Interactive Playground

Live Playground

Configuration
Presets
Properties
Numeric Constraints
MUI Variant
States
Live Preview

Enter a numeric value

Generated Code

tsx

<NumberField
  name="fieldName"
  label="Amount"
  placeholder="0"
  helperText="Enter a numeric value"
/>

Dashforge Capabilities

Built-in numeric handling with consistent layout behavior

NumberField is purpose-built for numeric input scenarios. It provides built-in validation, boundary enforcement, and proper null handling while maintaining consistency with Material Design patterns.

Consistent Layout System

Core Feature

NumberField inherits MUI TextField variants (outlined, filled, standard) providing a familiar and consistent visual system across all numeric inputs.

Native MUI variant prop support

Consistent with Material Design patterns

Seamless integration with existing forms

<NumberField
  name="quantity"
  label="Quantity"
  variant="outlined"
/>

Numeric Validation

Built-in

Built-in handling of min/max constraints, step increments, and proper numeric parsing. Stores number | null internally, never allows NaN.

Min/max boundary enforcement via inputProps

Step increment support for precise control

Proper null handling for empty values

<NumberField
  name="age"
  label="Age"
  inputProps={{ min: 0, max: 120 }}
/>

Reactive Visibility

Available Now

NumberField can participate in engine-driven visibility rules through visibleWhen. Use it when numeric input depends on other form state.

Conditional rendering via visibleWhen

Engine evaluates the predicate

Useful for dependent numeric fields

<NumberField
  name="quantity"
  label="Quantity"
  visibleWhen={(engine) => 
    engine.getNode('orderType')?.value === 'bulk'
  }
/>

Access Control (RBAC)

Control field visibility and interaction based on user permissions. Fields can be hidden, disabled, or set to readonly when users lack the required access. Integrates seamlessly with the Dashforge RBAC system.

Hide when unauthorized

<NumberField
  name="salary"
  label="Salary"
  access={{
    resource: 'employee.salary',
    action: 'read',
    onUnauthorized: 'hide',
  }}
/>

Disable when cannot edit

<NumberField
  name="discount"
  label="Discount"
  access={{
    resource: 'pricing.discount',
    action: 'update',
    onUnauthorized: 'disable',
  }}
/>

Readonly for view-only

<NumberField
  name="budget"
  label="Budget"
  access={{
    resource: 'project.budget',
    action: 'update',
    onUnauthorized: 'readonly',
  }}
/>

Combined with visibleWhen

<NumberField
  name="otherAmount"
  visibleWhen={(engine) =>
    engine.getNode('paymentType')?.value === 'custom'
  }
  access={{
    resource: 'payment.otherAmount',
    action: 'read',
    onUnauthorized: 'hide',
  }}
/>

Note: When combining visibleWhen with RBAC, both conditions must be satisfied. The field shows only if UI logic returns true AND the user has required permissions.

Form Integration

Real-world scenarios with numeric validation and boundaries

NumberField works in real form contexts with automatic type handling and validation. Try these live scenarios to experience DashForm integration with numeric inputs.

Simple Numeric Form

Try it: Enter numbers and submit the form

NumberField integrates seamlessly with DashForm through automatic field binding. It handles numeric type conversion (string → number | null) and validation from form context. Errors are displayed when the field has been touched or after form submission.

Live Preview
import { DashForm } from '@dashforge/forms';
import { NumberField } from '@dashforge/ui';

function ProductForm() {
  const handleSubmit = (data: FormData) => {
    console.log('Submitted:', data);
  };

  return (
    <DashForm
      defaultValues={{ quantity: null, price: null }}
      onSubmit={handleSubmit}
    >
      <NumberField
        name="quantity"
        label="Quantity"
        rules={{ required: 'Quantity is required' }}
      />
      <NumberField
        name="price"
        label="Price"
        rules={{ required: 'Price is required' }}
      />
      <button type="submit">Submit</button>
    </DashForm>
  );
}

// NumberField automatically:
// - Converts input to number type
// - Stores null for empty values (never NaN)
// - Displays validation errors when touched or after submission
// - Tracks dirty/touched state

Why it matters

Type-safe numeric input: No manual string-to-number conversion, no NaN edge cases, no custom validation for numeric types.

Min/Max Validation

Try it: Enter values outside the allowed range

NumberField enforces min/max constraints both visually (via inputProps) and through validation rules. Browser UI controls respect boundaries, and form validation provides clear error messages.

Live Preview

Enter your age

Enter temperature in Celsius

import { DashForm } from '@dashforge/forms';
import { NumberField } from '@dashforge/ui';

function RangeValidationForm() {
  return (
    <DashForm defaultValues={{ age: null, temperature: null }}>
      <NumberField
        name="age"
        label="Age (0-120)"
        helperText="Enter your age"
        inputProps={{ min: 0, max: 120 }}
        rules={{
          required: 'Age is required',
          min: { value: 0, message: 'Age must be at least 0' },
          max: { value: 120, message: 'Age cannot exceed 120' },
        }}
      />
      
      <NumberField
        name="temperature"
        label="Temperature (-40°C to 50°C)"
        helperText="Enter temperature in Celsius"
        inputProps={{ min: -40, max: 50, step: 0.1 }}
        rules={{
          required: 'Temperature is required',
          min: { value: -40, message: 'Temperature must be at least -40°C' },
          max: { value: 50, message: 'Temperature cannot exceed 50°C' },
        }}
      />
    </DashForm>
  );
}

// inputProps provides browser-level constraints
// rules provide form-level validation with custom messages

Why it matters

Dual-layer protection: Browser UI enforces boundaries visually, form validation catches edge cases with clear user feedback.

API Reference

Complete props and type definitions

PropTypeDefaultDescription
namestring-Field name for form integration (required)
labelstring-Label text displayed above the input
valuenumber | null-Controlled value (number | null). Empty input normalizes to null. Never NaN.
onChange(event) => void-Callback fired when the value changes
errorbooleanfalseIf true, displays error state. Explicit prop overrides form-provided error state.
helperTextstring-Helper text below input. Explicit prop overrides form-provided error messages.
disabledbooleanfalseIf true, the input is disabled
requiredbooleanfalseIf true, the input is marked as required
fullWidthbooleanfalseIf true, the input takes up the full width of its container
placeholderstring-Placeholder text when input is empty
inputPropsobject-Attributes for the input element (min, max, step)
variant'outlined' | 'filled' | 'standard'outlinedMUI TextField variant for visual styling
rulesValidationRules-Validation rules for DashForm integration (required, min, max, custom validators)
visibleWhen(engine) => boolean-Predicate for conditional rendering. Component evaluates on engine state changes. Returns null when false.

Explicit vs Form-Provided Props

When NumberField is used inside DashForm, values are automatically bound from the form context. You can explicitly pass error, helperText, value, or onChange to override form-provided behavior.

Implementation Notes

Technical details and best practices for numeric inputs

1

Numeric Parsing

NumberField automatically converts string input to number type. Empty values are stored as null, never as NaN. This ensures type-safe numeric handling across your forms.

2

Empty Values

When the input is empty, NumberField stores null instead of empty string or NaN. This makes validation logic cleaner and prevents edge cases with numeric operations.

3

Step Behavior

The step prop (via inputProps.step) controls increment/decrement buttons and arrow key behavior. Use step="0.1" for decimals or step="5" for larger increments.

4

DashForm Integration

When used inside DashForm, NumberField automatically integrates through DashFormBridge. It handles automatic field binding, numeric type conversion (string → number | null), and validation from form context. Errors are displayed when the field has been touched or after form submission. Explicit props override form-provided values.

5

Min/Max Validation

Use inputProps={{ min, max }} for browser-level constraints (visual spinner limits) and rules={{ min, max }} for form-level validation with custom error messages. Combining both provides dual-layer protection.

6

Type Safety

NumberField is fully typed with TypeScript. The value prop accepts number | string | null, and onChange events maintain type compatibility with both controlled and form-bound usage patterns.

On This Page