<c-number-field>
A field for a number — an integer, or one with decimals — shown with thousands separators as it is typed.
Usage
Value
The value is a number, or null while the field holds no digit. What the
field shows is grouped text — 1 234 567,89 — but the value is always the
plain number (1234567.89), so it needs no parsing. Bind it with v-model,
or listen for update:value:
<c-number-field v-model="amount" label="Amount" />
The value follows the text on every keystroke: typing 1234, gives 1234,
a lone - gives null. Only typing and stepping emit; setting value shows
the number without emitting it. change fires when the number is committed:
Enter or leaving the field after typing, each arrow-key or step-button step,
and the release that ends a held step button.
Unlike c-text-field type="number", the native number input, the field shows
separators and never changes the number on a scroll.
Separators
The thousands and decimal separators follow the page's lang: a space and
, under lang="fi", , and . under lang="en". Set group-separator
and decimal-separator to fix them for one field, or for the whole app with
applyDefaults({ 'c-number-field': { groupSeparator: ' ', decimalSeparator: ',' } }).
The field inserts the group separators itself, and typed or pasted ones are
ignored. Either . or , typed is read as the decimal separator — unless
it is the group separator — so the decimal key of any keyboard works. A
pasted 1,234.56 or 1.234,56 reads as 1234.56 either way.
Decimals
decimals is the most fraction digits the field takes. By default it is
0, an integer field that ignores the decimal key:
<c-number-field
v-model="price"
:decimals="2"
fixed-decimals
label="Price"
min="0"
>
<span slot="post">€</span>
</c-number-field>
Typing never pads the fraction. With fixed-decimals the field pads it to
exactly decimals digits when the user leaves it — 12,5 shows as 12,50 —
while the value stays 12.5. A value set with more fraction digits than
decimals is shown rounded.
The integer part takes up to 15 digits, the most a JavaScript number holds exactly.
Range
min and max never change what the user typed. A number outside them is
kept and emitted, and the host exposes the out-of-range custom state and a
read-only outOfRange property. The field shows no error of its own:
<c-number-field
v-model="count"
:error-message="error"
:invalid="!!error"
label="Participants"
max="50"
min="1"
@change="error = $event.target.outOfRange ? 'Enter 1 to 50' : ''"
/>
With min at 0 or above, the minus key is ignored.
Step
The buttons at the end of the field move the number one step up or down
(1 by default); holding one repeats. The arrow keys do the same, and Page Up
and Page Down move ten steps:
<c-number-field v-model="volume" label="Volume" max="100" min="0" step="5" />
A step lands on the grid of step counted from min (or 0): from a typed
12, a step of 5 goes up to 15 or down to 10. A typed number off the
grid stays as typed.
Stepping never leaves min and max: it stops on the bound, and the button
for that direction is disabled there. From an out-of-range number, a step
goes back to the nearest bound. An empty field counts from 0.
A stepped number is rounded to decimals, so a step finer than decimals
allows (0.5 on an integer field) does not step as written; keep the two
in line.
The buttons stay out of the tab order and never take focus, so tapping one
on a phone does not open the keyboard. To translate their accessible labels,
set texts: { stepUp: 'Lisää', stepDown: 'Vähennä' }, or app-wide with
applyDefaults.
Keyboard
On a phone the field asks for the numeric keyboard, or a decimal one when
decimals is set. Numeric keyboards on iOS have no minus key: there, a
negative number is reached by stepping below zero.
Use the pre and post slots for a currency sign or a unit; the step
buttons follow the post content.
Examples
<template>
<div>
<c-number-field v-model="count" hint="A whole number" label="Population" />
<p>Value: {{ count ?? 'null' }}</p>
</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
const count = ref<null | number>(null);
</script>
<template>
<div>
<c-number-field
v-model="price"
:decimals="2"
:min="0"
hint="Up to two decimals"
label="Price"
fixed-decimals
>
<span slot="post">€</span>
</c-number-field>
<p>Value: {{ price ?? 'null' }}</p>
</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
const price = ref<null | number>(1234.5);
</script>
<template>
<div>
<c-number-field
v-model="volume"
:max="100"
:min="0"
:step="5"
hint="0 to 100, in steps of 5"
label="Volume"
>
<span slot="post">%</span>
</c-number-field>
<p>Value: {{ volume ?? 'null' }}</p>
</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
const volume = ref<null | number>(50);
</script>
API reference
<c-number-field>
A field for a number — an integer, or one with decimals — shown with thousands separators as it is typed.
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
decimals | decimals | number | 0 app default | The most fraction digits the field takes; `0` makes it an integer field |
decimalSeparator | decimal-separator | string | '' app default | The decimal separator. Empty follows the page's `lang` (`,` for `fi`, `.` for `en`) |
disabled | disabled | boolean | false | Disable the field |
errorMessage | error-message | string | '' | Error message shown in place of the hint while the field is invalid |
fixedDecimals | fixed-decimals | boolean | false app default | Pad the fraction to exactly `decimals` digits when the field is left (`12,5` → `12,50`) |
groupSeparator | group-separator | string | '' app default | The thousands separator. Empty follows the page's `lang` (a space for `fi`, `,` for `en`) |
hideMessage | hide-message | boolean | false app default | Hide the message line — the hint and error messages under the field — and the room it keeps. |
hint | hint | string | '' | Hint text for the field |
invalid | invalid | boolean | false | Show the control as invalid: its `error-message`, when set, replaces the hint, and the control is marked `aria-invalid`. |
label | label | string | '' | Label of the field |
labelOnTop | label-on-top | boolean | false app default | Label on top of the field |
max | max | null | number | null | The largest number in range; a larger one is kept and reported as out of range |
min | min | null | number | null | The smallest number in range; a smaller one is kept and reported as out of range. At `0` or above, the minus key is ignored |
name | name | string | '' | The name the number submits under in a native `<form>`, written as a plain JS number (`1234.5`) |
placeholder | placeholder | string | '' | Placeholder of the input |
readonly | readonly | boolean | false | Mark as readonly |
required | required | boolean | false | Set the field as required |
shadow | shadow | boolean | false app default | Shadow variant of the field |
size | size | CFieldSize | 'default' app default | Field height: the 52px default (the shared control height) or the 36px `small` box |
step | step | number | 1 app default | The spacing of the grid the step buttons and arrow keys move along, counted from `min` (or `0`) |
texts | — | | {} app default | UI text overrides (i18n), merged over the English defaults. Objects have no attribute form — bind as a DOM property |
value | value | null | number | string | null | The number, or `null` when the field is empty. A string is read as the number it spells, and `''` as empty — what an attribute, or a plain `v-model` holding `null`, writes; the field always emits a number or `null` |
hideDetails deprecated | hide-details | boolean | false app default | Deprecated. Use `hide-message`. Hide the hint and error messages |
app default marks a prop you can set for every instance at once with applyDefaults() — an explicit attribute or property on an instance still wins.
Events
| Event | Detail | Description |
|---|---|---|
change | null | number | Fired when the number is committed, carrying it — `null` once the field holds no digit: Enter or leaving the field after typing, each arrow-key or step-button step, and the release that ends a held step button. Not fired when nothing changed since the last commit. |
input | void | Native bubbling input event fired alongside every value change so a plain Vue `v-model` works. No detail. |
update:value | null | number | v-model contract event fired whenever typing or a step changes the number. Not fired when only the text changes (a group separator, a trailing decimal separator) or when `value` is set. |
Methods
| Method | Signature | Description |
|---|---|---|
outOfRange | : boolean (read-only) | Whether the number is below `min` or above `max` (CONTEXT.md "Out of range") |
focus | (options?: FocusOptions): void | Focus its input, as `focus()` does on a native control: the element renders no box of its own to take it. |
Slots
| Slot | Description |
|---|---|
pre | Content before the number, such as a currency sign |
post | Content after the number, such as a unit; the step buttons follow it |
CSS parts
Style from outside with c-number-field::part(name) — parts are the library's only styling customization API.
| Part | Description |
|---|---|
input | The text input |
step-up | The button that steps the number up |
step-down | The button that steps the number down |
message | The hint / error message area below the field (always reserved unless `hide-message`) |
Custom states
Select on the host's live state with c-number-field:state(name) — combine with ::part() for per-state styling, e.g. c-number-field:state(checked)::part(indicator) targets the indicator only while checked.
| State | Description |
|---|---|
out-of-range | Present while the number is below `min` or above `max` |
Types
Importable from the package root: import type { … } from '@cscfi/csc-ui'
CNumberFieldTexts
UI texts of `c-number-field`, merged key by key over the English defaults.
export interface CNumberFieldTexts {
/** Accessible label of the step-down button. */
stepDown?: string;
/** Accessible label of the step-up button. */
stepUp?: string;
}CFieldSize shared
Field height of the form controls built on `c-input`. `default` is the 44px field; `small` is the 36px field. Owned here because the value passes from the wrapping control (`c-select`) into `c-input`.
export type CFieldSize = 'default' | 'small';