CSC Design System v4
VueFlavour Vue React Angular TypeScriptPrimaryCSC UI ColorsPrimarySecondaryAccentCustom ColorsRedOrangeGreenBluePurplePink
Guides Getting started Customization Data visualization Migration guide Componentsc-accordionc-alertc-autocompletec-badgec-breadcrumbc-buttonc-button-groupc-cardc-checkboxc-color-pickerc-csc-logoc-data-tablec-date-pickerc-dividerc-file-uploadc-iconc-icon-buttonc-linkc-listc-loaderc-login-buttonsc-login-cardc-mainc-menuc-messagec-modalc-navigation-buttonc-number-fieldc-otp-inputc-pagec-paginationc-popoverc-progress-barc-progress-circlec-radio-groupc-selectc-side-navigationc-sliderc-spinnerc-statusc-stepsc-switchc-tablec-tabsc-tagsc-text-fieldc-time-pickerc-toastsc-toolbarc-tooltipc-tree-select

<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

Basic
Vue React Angular TypeScript
<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>
Decimals
Vue React Angular TypeScript
<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>
Step
Vue React Angular TypeScript
<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

PropertyAttributeTypeDefaultDescription
decimalsdecimalsnumber0 app default The most fraction digits the field takes; `0` makes it an integer field
decimalSeparatordecimal-separatorstring'' app default The decimal separator. Empty follows the page's `lang` (`,` for `fi`, `.` for `en`)
disableddisabledbooleanfalse Disable the field
errorMessageerror-messagestring'' Error message shown in place of the hint while the field is invalid
fixedDecimalsfixed-decimalsbooleanfalse app default Pad the fraction to exactly `decimals` digits when the field is left (`12,5` → `12,50`)
groupSeparatorgroup-separatorstring'' app default The thousands separator. Empty follows the page's `lang` (a space for `fi`, `,` for `en`)
hideMessagehide-messagebooleanfalse app default Hide the message line — the hint and error messages under the field — and the room it keeps.
hinthintstring'' Hint text for the field
invalidinvalidbooleanfalse Show the control as invalid: its `error-message`, when set, replaces the hint, and the control is marked `aria-invalid`.
labellabelstring'' Label of the field
labelOnToplabel-on-topbooleanfalse app default Label on top of the field
maxmaxnull | numbernull The largest number in range; a larger one is kept and reported as out of range
minminnull | numbernull 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
namenamestring'' The name the number submits under in a native `<form>`, written as a plain JS number (`1234.5`)
placeholderplaceholderstring'' Placeholder of the input
readonlyreadonlybooleanfalse Mark as readonly
requiredrequiredbooleanfalse Set the field as required
shadowshadowbooleanfalse app default Shadow variant of the field
sizesizeCFieldSize'default' app default Field height: the 52px default (the shared control height) or the 36px `small` box
stepstepnumber1 app default The spacing of the grid the step buttons and arrow keys move along, counted from `min` (or `0`)
texts—CNumberFieldTexts{} app default UI text overrides (i18n), merged over the English defaults. Objects have no attribute form — bind as a DOM property
valuevaluenull | number | stringnull 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-detailsbooleanfalse 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

EventDetailDescription
changenull | numberFired 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.
inputvoidNative bubbling input event fired alongside every value change so a plain Vue `v-model` works. No detail.
update:valuenull | numberv-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

MethodSignatureDescription
outOfRange: boolean (read-only)Whether the number is below `min` or above `max` (CONTEXT.md "Out of range")
focus(options?: FocusOptions): voidFocus its input, as `focus()` does on a native control: the element renders no box of its own to take it.

Slots

SlotDescription
preContent before the number, such as a currency sign
postContent 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.

PartDescription
inputThe text input
step-upThe button that steps the number up
step-downThe button that steps the number down
messageThe 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.

StateDescription
out-of-rangePresent 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';