NumberInput

NumberInputは、ユーザーからの数値入力を取得するために使用されるコンポーネントです。

<NumberInput placeholder="placeholder" />

使い方

import { NumberInput } from "@yamada-ui/react"

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

import { NumberInput } from "@workspaces/ui"

<NumberInput />

バリアントを変更する

<VStack>
  <For each={["outline", "filled", "flushed"]}>
    {(variant) => (
      <NumberInput
        key={variant}
        variant={variant}
        placeholder={toTitleCase(variant)}
      />
    )}
  </For>
</VStack>

サイズを変更する

<VStack>
  <For each={["xs", "sm", "md", "lg", "xl"]}>
    {(size) => (
      <NumberInput key={size} size={size} placeholder={`Size (${size})`} />
    )}
  </For>
</VStack>

デフォルトの値を設定する

デフォルトの値を設定する場合は、defaultValueに文字列または数値を設定します。

<NumberInput defaultValue={18} placeholder="Order Quantity" />

最小・最大値を設定する

最小値と最大値を設定する場合は、minまたはmaxに数値を設定します。

<NumberInput defaultValue={18} min={8} max={31} placeholder="Order Quantity" />

ステップ値を設定する

ステップ値を設定する場合は、stepに数値を設定します。

<NumberInput
  defaultValue={15}
  step={5}
  min={5}
  max={30}
  placeholder="Order Quantity"
/>

小数点を設定する

小数点を設定する場合は、precisionに数値を設定します。

<NumberInput
  defaultValue={15}
  precision={2}
  step={0.2}
  placeholder="Order Quantity"
/>

ブラー時の値のクランプを無効にする

デフォルトでは、ユーザーの自由な数値入力を受け付けますが、minまたはmaxを超える数値は、ブラー時に自動的に調整されます。この自動的に調整される動作を無効にする場合は、clampValueOnBlurをfalseに設定します。

<NumberInput
  defaultValue={15}
  max={30}
  clampValueOnBlur={false}
  placeholder="Order Quantity"
/>

範囲外の値を許可する

範囲外の値を許可する場合は、keepWithinRangeをfalseに設定します。

<NumberInput
  defaultValue={15}
  max={30}
  keepWithinRange={false}
  clampValueOnBlur={false}
  placeholder="Order Quantity"
/>

無効にする

無効にする場合は、disabledをtrueに設定します。

<VStack>
  <For each={["outline", "filled", "flushed"]}>
    {(variant) => (
      <NumberInput
        key={variant}
        disabled
        variant={variant}
        placeholder={toTitleCase(variant)}
      />
    )}
  </For>
</VStack>

読み取り専用にする

読み取り専用にする場合は、readOnlyをtrueに設定します。

<VStack>
  <For each={["outline", "filled", "flushed"]}>
    {(variant) => (
      <NumberInput
        key={variant}
        readOnly
        variant={variant}
        placeholder={toTitleCase(variant)}
      />
    )}
  </For>
</VStack>

無効な入力にする

無効な入力にする場合は、invalidをtrueに設定します。

<VStack>
  <For each={["outline", "filled", "flushed"]}>
    {(variant) => (
      <NumberInput
        key={variant}
        invalid
        variant={variant}
        placeholder={toTitleCase(variant)}
      />
    )}
  </For>
</VStack>

ボーダーの色を変更する

ボーダーの色を変更する場合は、focusBorderColorまたはerrorBorderColorに値を設定します。

<VStack>
  <NumberInput
    focusBorderColor="green.500"
    placeholder="Custom focus border color"
  />
  <NumberInput
    errorBorderColor="orange.500"
    invalid
    placeholder="Custom invalid border color"
  />
</VStack>

プレースホルダーの色を変更する

プレースホルダーの色を変更する場合は、_placeholderに値を設定します。

<NumberInput
  placeholder="Custom placeholder"
  _placeholder={{ color: "blue.500" }}
/>

ステッパーをカスタマイズする

ステッパーをカスタマイズする場合は、incrementPropsまたはdecrementPropsにpropsを設定します。

<NumberInput
  placeholder="Order Quantity"
  incrementProps={{ children: <PlusIcon /> }}
  decrementProps={{ children: <MinusIcon /> }}
/>

コンポーネントをカスタマイズする

コンポーネントをカスタマイズする場合は、useNumberInputを使用します。

const { getInputProps, getIncrementProps, getDecrementProps } = useNumberInput({
  step: 0.01,
  defaultValue: 3.14,
  min: 3,
  max: 4,
  precision: 2,
})

return (
  <HStack maxW="xs" gap="sm">
    <IconButton
      icon={<PlusIcon fontSize="2xl" />}
      {...getIncrementProps()}
      aria-label="Increment"
    />
    <Input {...getInputProps()} aria-label="Number Input" />
    <IconButton
      icon={<MinusIcon fontSize="2xl" />}
      {...getDecrementProps()}
      aria-label="Decrement"
    />
  </HStack>
)

こちらのコードを使用する場合は、"use client"をファイルの上部に追加する必要があります。

制御する

const [value, setValue] = useState(18)

return (
  <NumberInput
    value={value}
    onChange={(_, valueAsNumber) => setValue(valueAsNumber)}
    placeholder="Order Quantity"
  />
)

こちらのコードを使用する場合は、"use client"をファイルの上部に追加する必要があります。

Props

Prop	デフォルト	型 / 説明
`as`	-	`As` The HTML element to render.
`asChild`	-	`boolean` Merges its props onto its immediate child.
`css`	-	`CSSObject \| CSSObject[]` The CSS object.
`colorScheme`	-	`"amber" \| "black" \| "blackAlpha" \| "blue" \| "cyan" \| "danger" \| "emerald" \| "error" \| "flashy" \| "fuchsia" ...` Set color scheme variables.
`size`	`"md"`	`"2xl" \| "lg" \| "md" \| "sm" \| "xl" \| "xs"` The size of the component.
`variant`	`"outline"`	`"filled" \| "flushed" \| "outline" \| "plain"` The variant of the component.
`allowMouseWheel`	`false`	`boolean` If `true`, the input's value will change based on mouse wheel.
`clampValueOnBlur`	`true`	`boolean` This controls the value update when you blur out of the input. - If `true` and the value is greater than `max`, the value will be reset to `max`. - Else, the value remains the same.
`controlProps`	-	`NumberInputControlProps` The props for the control element.
`decrementProps`	-	`NumberInputDecrementButtonProps` The props for the decrement button element.
`defaultValue`	-	`number \| string` The initial value of the counter. Should be less than `max` and greater than `min`.
`elementProps`	-	`InputGroup.ElementProps` The props for the end element.
`errorBorderColor`	-	`"-moz-initial" \| "AccentColor" \| "AccentColorText" \| "ActiveBorder" \| "ActiveCaption" \| "ActiveText" \| "aliceblue" \| "amber.100" \| "amber.200" \| "amber.300" ...` The border color when the input is invalid.
`focusBorderColor`	-	`"-moz-initial" \| "AccentColor" \| "AccentColorText" \| "ActiveBorder" \| "ActiveCaption" \| "ActiveText" \| "aliceblue" \| "amber.100" \| "amber.200" \| "amber.300" ...` The border color when the input is focused.
`focusInputOnChange`	`true`	`boolean` If `true`, the input will be focused as you increment or decrement the value with the button.
`format`	-	`(value: number \| string) => string` If using a custom display format, this converts the default format to the custom format.
`getAriaValueText`	-	`(value: number \| string) => string \| undefined` This is used to format the value so that screen readers can speak out a more human-friendly value. It is used to set the `aria-valuetext` property of the input.
`htmlSize`	-	`number` The native HTML `size` attribute to be passed to the `input`.
`incrementProps`	-	`NumberInputIncrementButtonProps` The props for the increment button element.
`invalid`	`false`	`boolean` If `true`, the field will be invalid.
`isValidCharacter`	-	`(value: string) => boolean` Whether the pressed key should be allowed in the input. The default behavior is to allow DOM floating point characters defined by /^[Ee0-9+\-.]$/.
`keepWithinRange`	`true`	`boolean` This controls the value update behavior in general. - If `true` and you use the stepper or up/down arrow keys, the value will not exceed the `max` or go lower than `min`. - If `false`, the value will be allowed to go out of range.
`max`	`Number.MAX_SAFE_INTEGER`	`number` The maximum value of the counter
`min`	`Number.MIN_SAFE_INTEGER`	`number` The minimum value of the counter
`onChange`	-	`(valueAsString: string, valueAsNumber: number) => void` The callback fired when the value changes.
`parse`	-	`(value: string) => string` If using a custom display format, this converts the custom format to a format `parseFloat` understands.
`precision`	-	`number` The number of decimal points used to round the value.
`rootProps`	-	`InputGroup.RootProps` The props for the root element.
`step`	`1`	`number` The step used to increment or decrement the value.
`value`	-	`number \| string` The value of the counter. Should be less than `max` and greater than `min`.

アクセシビリティ

NumberInputは、アクセシビリティに関してWAI-ARIA - Spinbutton Patternに従います。

Field.Rootを使用しない場合は、NumberInputにaria-labelまたはaria-labelledbyを設定します。

<NumberInput aria-label="Age" />

<VStack gap="sm">
  <Text as="h3" id="label">
    Age
  </Text>

  <NumberInput aria-labelledby="label" />
</VStack>

キー	説明	状態
`ArrowUp`	`step`の値に基づいて値を増加します。	-
`ArrowDown`	`step`の値に基づいて値を減少します。	-
`Home`	`min`の値を設定します。	-
`End`	`max`の値を設定します。	-
`Shift` + `ArrowUp`	`step`の10倍で値を増加します。	-
`Shift` + `ArrowDown`	`step`の10倍で値を減少します。	-
`Meta` + `ArrowUp`, `Ctrl` + `ArrowUp`	`step`の0.1倍で値を増加します。	-
`Meta` + `ArrowDown`, `Ctrl` + `ArrowDown`	`step`の0.1倍で値を減少します。	-

ARIAロールと属性

コンポーネント	ロールと属性	使い方
`NumberInput`	`role="spinbutton"`	スピンボタンであることを示します。
	`aria-valuemin`	`min`の値を設定します。
	`aria-valuemax`	`max`の値を設定します。
	`aria-valuenow`	現在の値を設定します。
	`aria-valuetext`	現在の値を設定します。
	`aria-invalid`	`invalid`が設定されている場合、または値が範囲外の場合は`"true"`を設定します。
	`aria-describedby`	`NumberInput`が`Field.Root`内にあり、`Field.Root`に`errorMessage`または`helperMessage`、もしくは`Field.ErrorMessage`または`Field.HelperMessage`が設定されている場合は、その`id`を設定します。
	`aria-disabled`	`disabled`が設定されている場合は`"true"`を設定します。
	`aria-readonly`	`readOnly`が設定されている場合は`"true"`を設定します。
	`aria-required`	`required`が設定されている場合は`"true"`を設定します。
`NumberInputIncrementButton`	`aria-label`	`"増加"`を設定します。
`NumberInputDecrementButton`	`aria-label`	`"減少"`を設定します。

類似のコンポーネント

Textareaは、複数行のテキスト入力を取得するために使用されるコンポーネントです。

PinInputは、ピンコードやOTP(ワンタイムパスワード)の入力を取得するために使用されるコンポーネントです。

PasswordInputは、表示・非表示の切り替えができるパスワード入力用のコンポーネントです。

Inputは、ユーザーからのテキスト入力を取得するために使用されるコンポーネントです。

Editableは、インラインで編集可能なテキスト入力を取得するために使用されるコンポーネントです。

FileInputは、ユーザーがファイルを選択するために使用されるコンポーネントです。

Autocompleteは、ユーザーのテキスト入力に応じて候補を表示するために使用されるコンポーネントです。

Switchは、オンとオフの状態を切り替えるために使用されるコンポーネントです。

使用しているコンポーネント・フック

Buttonは、フォームの送信、モーダルの開閉など、ユーザーが操作できるインタラクティブなコンポーネントです。

Inputは、ユーザーからのテキスト入力を取得するために使用されるコンポーネントです。

Groupは、複数の要素をまとめて扱うためのコンポーネントです。

Iconは、プロジェクトに使用できる一般的なアイコンコンポーネントです。

Fieldは、フォーム要素に、ラベル、ヘルパーメッセージ、エラーメッセージなどをグループ化するために使用されるコンポーネントです。

useCounterは、数値を増加または減少させるためのカスタムフックです。

useIntervalは、指定された間隔で関数を実行するカスタムフックです。