Number Input | Park UI

Installation

npx @park-ui/cli@next add number-input

Add Component

Copy the code snippet below into you components folder.

'use client'
import { NumberInput } from '@ark-ui/react/number-input'
import { ChevronDownIcon, ChevronUpIcon } from 'lucide-react'
import type { ComponentProps } from 'react'
import { createStyleContext } from 'styled-system/jsx'
import { numberInput } from 'styled-system/recipes'

const { withProvider, withContext } = createStyleContext(numberInput)

export type RootProps = ComponentProps<typeof Root>
export const Root = withProvider(NumberInput.Root, 'root')
export const RootProvider = withProvider(NumberInput.RootProvider, 'root')
export const DecrementTrigger = withContext(NumberInput.DecrementTrigger, 'decrementTrigger', {
  defaultProps: { children: <ChevronDownIcon /> },
})
export const IncrementTrigger = withContext(NumberInput.IncrementTrigger, 'incrementTrigger', {
  defaultProps: { children: <ChevronUpIcon /> },
})
export const Input = withContext(NumberInput.Input, 'input')
export const Label = withContext(NumberInput.Label, 'label')
export const Scrubber = withContext(NumberInput.Scrubber, 'scrubber')
export const ValueText = withContext(NumberInput.ValueText, 'valueText')
export const Control = withContext(NumberInput.Control, 'control', {
  defaultProps: {
    children: (
      <>
        <IncrementTrigger />
        <DecrementTrigger />
      </>
    ),
  },
})

export { NumberInputContext as Context } from '@ark-ui/react/number-input'

Integrate Recipe

Integrate this recipe in to your Panda config.

/** biome-ignore-all lint/complexity/useLiteralKeys: Need to improve types in Panda CSS */
import { numberInputAnatomy } from '@ark-ui/react/number-input'
import { defineSlotRecipe } from '@pandacss/dev'
import { input } from './input'

const trigger = {
  alignItems: 'center',
  color: 'fg.muted',
  cursor: 'pointer',
  display: 'flex',
  flex: '1',
  justifyContent: 'center',
  lineHeight: '1',
  transition: 'common',
  userSelect: 'none',
  _icon: {
    boxSize: '1em',
  },
  _hover: {
    bg: 'bg.muted',
  },
  _active: {
    bg: 'bg.emphasized',
  },
}

export const numberInput = defineSlotRecipe({
  className: 'number-input',
  slots: numberInputAnatomy.keys(),
  base: {
    root: {
      isolation: 'isolate',
      position: 'relative',
      _disabled: {
        layerStyle: 'disabled',
      },
    },
    control: {
      borderStartWidth: '1px',
      display: 'flex',
      divideY: '1px',
      flexDirection: 'column',
      height: 'calc(100% - 2px)',
      insetEnd: '0px',
      margin: '1px',
      position: 'absolute',
      top: '0',
      width: 'var(--stepper-width)',
      zIndex: '1',
    },
    input: {
      ...input.base,
      verticalAlign: 'top',
      pe: 'calc(var(--stepper-width) + 0.5rem)',
    },
    label: {
      color: 'fg.default',
      fontWeight: 'medium',
    },
    incrementTrigger: {
      ...trigger,
      borderTopRightRadius: 'l2',
    },
    decrementTrigger: {
      ...trigger,
      borderBottomRightRadius: 'l2',
    },
  },
  defaultVariants: {
    size: 'md',
    variant: 'outline',
  },
  variants: {
    size: {
      sm: {
        control: {
          '--stepper-width': 'sizes.4.5',
        },
        input: input.variants?.['size']?.['sm'],
      },
      md: {
        control: {
          '--stepper-width': 'sizes.5',
        },
        input: input.variants?.['size']?.['md'],
      },
      lg: {
        control: {
          '--stepper-width': 'sizes.5.5',
        },
        input: input.variants?.['size']?.['lg'],
      },
      xl: {
        control: {
          '--stepper-width': 'sizes.6',
        },
        input: input.variants?.['size']?.['xl'],
      },
    },
    variant: {
      outline: {
        input: input.variants?.['variant']?.['outline'],
      },
    },
  },
})

Usage

import { NumberInput } from '@/components/ui'

<NumberInput.Root>
  <NumberInput.Label />
  <NumberInput.ValueText />
  <NumberInput.Control>
    <NumberInput.IncrementTrigger />
    <NumberInput.DecrementTrigger />
  </NumberInput.Control>
  <NumberInput.Scrubber />
  <NumberInput.Input />
</NumberInput.Root>

Info

If you prefer a closed component composition, check out the snippet below.

Shortcuts

The NumberInput component provides a set of shortcuts for common use cases

NumberInput.Control

This component renders the NumberInput.IncrementTrigger and NumberInput.DecrementTrigger within it by default.

Writing this:

<NumberInput.Control />

is shorthand for writing this if you don't need to customize the triggers:

<NumberInput.Control>
  <NumberInput.IncrementTrigger />
  <NumberInput.DecrementTrigger />
</NumberInput.Control>

Examples

Sizes

Pass the size prop to change the size of the number input.

Formatting

Pass the formatOptions prop to format the number input value. The value of this maps to Intl.NumberFormatOptions and is applied based on the current locale.

Min and Max

Pass the min and max props to set the minimum and maximum values of the number input.

If value entered is less than min or greater than max, the value will be clamped to the nearest boundary on blur, or enter key press.

Step

Pass the step prop to change the increment or decrement interval of the number input.

Controlled

Pass the value and onValueChange props to control the value of the number input.

Mouse Wheel

Pass the allowMouseWheel prop to enable or disable the mouse wheel to change the value of the number input.

Disabled

Pass the disabled prop to disable the number input.

Invalid

Use the Field component and the invalid prop to indicate that the number input is invalid.

Quantity

The entry is invalid

Helper Text

Compose the Field and Field.HelperText components to add helper text to the number input.

Quantity

Please enter a number between 5 and 50

Element

Here's an example of how to compose the number input with the input group component to add an element on either the left or right.

Scrubber

Use the NumberInput.Scrubber component to make the number input supports scrubber interactions.

Closed Component

Here is an example of how to use the NumberInput component in a closed manner.

import { forwardRef, type InputHTMLAttributes, type RefObject } from 'react'
import { NumberInput as StyledNumberInput } from '@/components/ui'

export interface NumberInputProps extends StyledNumberInput.RootProps {
  rootRef?: RefObject<HTMLDivElement | null>
  inputProps?: InputHTMLAttributes<HTMLInputElement>
}

export const NumberInput = forwardRef<HTMLInputElement, NumberInputProps>(
  function NumberInput(props, ref) {
    const { inputProps, rootRef, ...rest } = props
    return (
      <StyledNumberInput.Root ref={rootRef} {...rest}>
        <StyledNumberInput.Control />
        <StyledNumberInput.Input ref={ref} {...inputProps} />
      </StyledNumberInput.Root>
    )
  },
)

and use it like this:

<NumberInput defaultValue="42" />

Props

Root

Prop	Default	Type
`size`	`'md'`	`'sm' \| 'md' \| 'lg' \| 'xl'`
`variant`	`'outline'`	`'outline'`
`allowOverflow`	`true`	`boolean` Whether to allow the value overflow the min/max range
`clampValueOnBlur`	`true`	`boolean` Whether to clamp the value when the input loses focus (blur)
`focusInputOnChange`	`true`	`boolean` Whether to focus input when the value changes
`inputMode`	`\decimal\`	`InputMode` Hints at the type of data that might be entered by the user. It also determines the type of keyboard shown to the user on mobile devices
`locale`	`\en-US\`	`string` The current locale. Based on the BCP 47 definition.
`max`	`Number.MAX_SAFE_INTEGER`	`number` The maximum value of the number input
`min`	`Number.MIN_SAFE_INTEGER`	`number` The minimum value of the number input
`pattern`	`\-?[0-9]*(.[0-9]+)?\`	`string` The pattern used to check the <input> element's value against
`spinOnPress`	`true`	`boolean` Whether to spin the value when the increment/decrement button is pressed
`step`	`1`	`number` The amount to increment or decrement the value by
`allowMouseWheel`		`boolean` Whether to allow mouse wheel to change the value
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior.
`defaultValue`		`string` The initial value of the input when rendered. Use when you don't need to control the value of the input.
`disabled`		`boolean` Whether the number input is disabled.
`form`		`string` The associate form of the input element.
`formatOptions`		`NumberFormatOptions` The options to pass to the `Intl.NumberFormat` constructor
`id`		`string` The unique identifier of the machine.
`ids`		`Partial<{ root: string label: string input: string incrementTrigger: string decrementTrigger: string scrubber: string }>` The ids of the elements in the number input. Useful for composition.
`invalid`		`boolean` Whether the number input value is invalid.
`name`		`string` The name attribute of the number input. Useful for form submission.
`onFocusChange`		`(details: FocusChangeDetails) => void` Function invoked when the number input is focused
`onValueChange`		`(details: ValueChangeDetails) => void` Function invoked when the value changes
`onValueInvalid`		`(details: ValueInvalidDetails) => void` Function invoked when the value overflows or underflows the min/max range
`readOnly`		`boolean` Whether the number input is readonly
`required`		`boolean` Whether the number input is required
`translations`		`IntlTranslations` Specifies the localized strings that identifies the accessibility elements and their states
`value`		`string` The controlled value of the input