feat(NumberField): add stepSnapping prop to disable snapping values to step (#1593) (#1696)

blakemann · web-flow · commit d6016186c548 · 2025-03-14T15:22:22.000+08:00
diff --git a/docs/content/meta/NumberFieldRoot.md b/docs/content/meta/NumberFieldRoot.md
@@ -80,6 +80,13 @@
     'type': 'number',
     'required': false,
     'default': '1'
+  },
+  {
+    'name': 'stepSnapping',
+    'description': '<p>When <code>false</code>, prevents the value from snapping to the nearest increment of the step value.</p>\n',
+    'type': 'boolean',
+    'required': false,
+    'default': true
   }
 ]" />
 
diff --git a/packages/core/src/NumberField/NumberField.test.ts b/packages/core/src/NumberField/NumberField.test.ts
@@ -197,7 +197,7 @@ describe('numberField', () => {
     })
 
     it('should compute min-max with step correctly', async () => {
-      const { input } = setup({ min: 2, max: 21, step: 3 })
+      const { input } = setup({ min: 2, max: 21, step: 3, stepSnapping: true })
 
       expect(input.value).toBe('')
       await fireEvent.keyDown(input, { key: kbd.ARROW_UP }) // 2
@@ -208,9 +208,20 @@ describe('numberField', () => {
       await fireEvent.keyDown(input, { key: kbd.ARROW_UP }) // 17
       await fireEvent.keyDown(input, { key: kbd.ARROW_UP }) // 20
       expect(input.value).toBe('20')
-      await fireEvent.keyDown(input, { key: kbd.ARROW_UP }) // 20 (max)
+      await fireEvent.keyDown(input, { key: kbd.ARROW_UP }) // 20 (max snapped to step)
       expect(input.value).toBe('20')
     })
+
+    it('should compute min-max with step correctly when stepSnapping false', async () => {
+      const { input } = setup({ min: 17, max: 21, step: 3, stepSnapping: false })
+
+      expect(input.value).toBe('')
+      await fireEvent.keyDown(input, { key: kbd.ARROW_UP }) // 17
+      await fireEvent.keyDown(input, { key: kbd.ARROW_UP }) // 20
+      expect(input.value).toBe('20')
+      await fireEvent.keyDown(input, { key: kbd.ARROW_UP }) // 21 (max not snapped to step)
+      expect(input.value).toBe('21')
+    })
   })
 
   describe('given setting the input value manually', async () => {
diff --git a/packages/core/src/NumberField/NumberFieldRoot.vue b/packages/core/src/NumberField/NumberFieldRoot.vue
@@ -14,6 +14,8 @@ export interface NumberFieldRootProps extends PrimitiveProps, FormFieldProps {
   max?: number
   /** The amount that the input value changes with each increment or decrement "tick". */
   step?: number
+  /** When `false`, prevents the value from snapping to the nearest increment of the step value */
+  stepSnapping?: boolean
   /** Formatting options for the value displayed in the number field. This also affects what characters are allowed to be typed by the user. */
   formatOptions?: Intl.NumberFormatOptions
   /** The locale to use for formatting dates */
@@ -63,9 +65,10 @@ const props = withDefaults(defineProps<NumberFieldRootProps>(), {
   as: 'div',
   defaultValue: undefined,
   step: 1,
+  stepSnapping: true,
 })
 const emits = defineEmits<NumberFieldRootEmits>()
-const { disabled, min, max, step, formatOptions, id, locale: propLocale } = toRefs(props)
+const { disabled, min, max, step, stepSnapping, formatOptions, id, locale: propLocale } = toRefs(props)
 
 const modelValue = useVModel(props, 'modelValue', emits, {
   defaultValue: props.defaultValue,
@@ -147,7 +150,7 @@ function setInputValue(val: string) {
 function clampInputValue(val: number) {
   // Clamp to min and max, round to the nearest step, and round to specified number of digits
   let clampedValue: number
-  if (step.value === undefined || isNaN(step.value))
+  if (step.value === undefined || isNaN(step.value) || !stepSnapping.value)
     clampedValue = clamp(val, min.value, max.value)
   else
     clampedValue = snapValueToStep(val, min.value, max.value, step.value)
