XDS — Design System

NumberInput@xds/core · XDSNumberInput v0.0.13

Usage

A form input for numeric values with built-in validation, min/max constraints, and step controls. Use NumberInput for quantities, measurements, percentages, and similar inputs.

ts
import {XDSNumberInput} from '@xds/core/NumberInput'

Best practices

Guidance	Practices
Do	Set min, max, and step to guide users toward valid values.
Do	Show units (e.g. "%" or "GB") so users know what the number represents.
Don't	Use NumberInput for free-form text that happens to contain numbers — use TextInput instead.
Don't	Set both isOptional and isRequired on the same field.

Examples

Common configurations, variations, and states.

NumberInput — ClearableNumber input with a clear button, unit suffix, and min/max constraint

tsx
'use client';
import {useState} from 'react';
import {XDSNumberInput} from '@xds/core/NumberInput';
import {XDSCenter} from '@xds/core/Center';
export default function NumberInputClearableNumberInput() {
  const [value, setValue] = useState<number | null>(75);
  return (
    <XDSCenter width={300}>
      <XDSNumberInput
        label="Progress"
        units="%"
        min={0}
        max={100}
        value={value}
        onChange={setValue}
        hasClear
      />
    </XDSCenter>
  );
}

NumberInput — Range ConstrainedNumber input with min/max boundaries and a helper description

tsx
'use client';
import {useState} from 'react';
import {XDSNumberInput} from '@xds/core/NumberInput';
import {XDSCenter} from '@xds/core/Center';
export default function NumberInputRangeNumberInput() {
  const [value, setValue] = useState<number | null>(3);
  return (
    <XDSCenter width={300}>
      <XDSNumberInput
        label="Team Size"
        placeholder="1–50"
        min={1}
        max={50}
        description="Number of people on the team"
        value={value}
        onChange={setValue}
      />
    </XDSCenter>
  );
}

NumberInput — Status VariantsNumber inputs showing error, warning, and success validation states

tsx
'use client';
import {useState} from 'react';
import {XDSNumberInput} from '@xds/core/NumberInput';
import {XDSVStack} from '@xds/core/Stack';
import {XDSCenter} from '@xds/core/Center';
export default function NumberInputStatuses() {
  const [error, setError] = useState<number | null>(-5);
  const [warning, setWarning] = useState<number | null>(150);
  const [success, setSuccess] = useState<number | null>(25);
  return (
    <XDSCenter width={300}>
      <XDSVStack gap={4}>
        <XDSNumberInput
          label="Budget"
          value={error}
          onChange={setError}
          status={{type: 'error', message: 'Must be a positive amount'}}
        />
        <XDSNumberInput
          label="Headcount"
          value={warning}
          onChange={setWarning}
          status={{type: 'warning', message: 'Exceeds typical team size'}}
        />
        <XDSNumberInput
          label="Completion"
          units="%"
          value={success}
          onChange={setSuccess}
          status={{type: 'success', message: 'On track'}}
        />
      </XDSVStack>
    </XDSCenter>
  );
}

NumberInput — With UnitsNumber input with a percentage unit suffix and valid range

tsx
'use client';
import {useState} from 'react';
import {XDSNumberInput} from '@xds/core/NumberInput';
import {XDSCenter} from '@xds/core/Center';
export default function NumberInputWithUnits() {
  const [value, setValue] = useState<number | null>(50);
  return (
    <XDSCenter width={300}>
      <XDSNumberInput
        label="Discount"
        placeholder="Enter discount"
        min={0}
        max={100}
        units="%"
        value={value}
        onChange={setValue}
      />
    </XDSCenter>
  );
}

Showcase source

tsx
import {XDSNumberInput} from '@xds/core/NumberInput';
export default function NumberInputShowcase() {
  return (
    <div style={{maxWidth: 300}}>
      <XDSNumberInput
        label="Quantity"
        placeholder="Enter quantity"
        value={0}
        onChange={() => {}}
      />
    </div>
  );
}

Usage

A form input for numeric values with built-in validation, min/max constraints, and step controls. Use NumberInput for quantities, measurements, percentages, and similar inputs.

import {XDSNumberInput} from '@xds/core/NumberInput'

Best practices

Guidance	Practices
Do	Set min, max, and step to guide users toward valid values.
Do	Show units (e.g. "%" or "GB") so users know what the number represents.
Don't	Use NumberInput for free-form text that happens to contain numbers — use TextInput instead.
Don't	Set both isOptional and isRequired on the same field.

tsx

'use client'; import {useState} from 'react'; import {XDSNumberInput} from '@xds/core/NumberInput'; import {XDSCenter} from '@xds/core/Center'; export default function NumberInputClearableNumberInput() { const [value, setValue] = useState<number | null>(75); return ( <XDSCenter width={300}> <XDSNumberInput label="Progress" units="%" min={0} max={100} value={value} onChange={setValue} hasClear /> </XDSCenter> ); }

tsx

'use client'; import {useState} from 'react'; import {XDSNumberInput} from '@xds/core/NumberInput'; import {XDSCenter} from '@xds/core/Center'; export default function NumberInputRangeNumberInput() { const [value, setValue] = useState<number | null>(3); return ( <XDSCenter width={300}> <XDSNumberInput label="Team Size" placeholder="1–50" min={1} max={50} description="Number of people on the team" value={value} onChange={setValue} /> </XDSCenter> ); }

tsx

'use client'; import {useState} from 'react'; import {XDSNumberInput} from '@xds/core/NumberInput'; import {XDSVStack} from '@xds/core/Stack'; import {XDSCenter} from '@xds/core/Center'; export default function NumberInputStatuses() { const [error, setError] = useState<number | null>(-5); const [warning, setWarning] = useState<number | null>(150); const [success, setSuccess] = useState<number | null>(25); return ( <XDSCenter width={300}> <XDSVStack gap={4}> <XDSNumberInput label="Budget" value={error} onChange={setError} status={{type: 'error', message: 'Must be a positive amount'}} /> <XDSNumberInput label="Headcount" value={warning} onChange={setWarning} status={{type: 'warning', message: 'Exceeds typical team size'}} /> <XDSNumberInput label="Completion" units="%" value={success} onChange={setSuccess} status={{type: 'success', message: 'On track'}} /> </XDSVStack> </XDSCenter> ); }

tsx

'use client'; import {useState} from 'react'; import {XDSNumberInput} from '@xds/core/NumberInput'; import {XDSCenter} from '@xds/core/Center'; export default function NumberInputWithUnits() { const [value, setValue] = useState<number | null>(50); return ( <XDSCenter width={300}> <XDSNumberInput label="Discount" placeholder="Enter discount" min={0} max={100} units="%" value={value} onChange={setValue} /> </XDSCenter> ); }

tsx

import {XDSNumberInput} from '@xds/core/NumberInput'; export default function NumberInputShowcase() { return ( <div style={{maxWidth: 300}}> <XDSNumberInput label="Quantity" placeholder="Enter quantity" value={0} onChange={() => {}} /> </div> ); }