CSC Design System v4.0.1
VueFlavour Vue React Angular TypeScript
Flavour Vue React Angular TypeScript
PrimaryCSC UI Colors Primary Secondary AccentCustom Colors Red Orange Green Blue Purple Pink
CSC UI Colors Primary Secondary AccentCustom Colors Red Orange Green Blue Purple Pink
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-text-field>

A text field for a single line of text, or several lines under `rows`, with a label, a hint and an error message.

Usage

Value

The value is the text in the field as a string. Bind it with v-model, or listen for update:value, which fires on every keystroke:

<c-text-field v-model="name" label="Name" />

change fires when the text is committed — Enter, or leaving the field after an edit — so save or validate there rather than on every keystroke.

In a native <form> the text submits under name, and Enter submits the form; see In a form on c-button.

type maps to the native input type: password adds a toggle that reveals the text, and number honours min, max and step. Setting rows above 1 renders a textarea.

Input mask

mask makes the typed text follow a pattern, such as a phone number, a postal code or an account number. In the pattern, # stands for a digit, A for a letter and * for a letter or a digit; every other character is a literal the field inserts itself, and \ makes the next character a literal (\#).

<c-text-field v-model="phone" label="Phone" mask="+358 ## ### ####" />
Token Takes
# A digit
A A letter
* A letter or digit
\x x as a literal
[…] Optional section

Characters a token does not take are dropped as they are typed or pasted. A literal appears only once the next character arrives, so typing 40 into the mask above shows +358 40, an empty field stays empty, and Backspace never gets stuck on a separator. Typing or pasting the literals yourself works too: +358401234567 fills the field the same way. A mask of digits only brings up the numeric keyboard.

While the user types, a faint mask guide behind the text shows the rest of the pattern — +358 __ ___ ____ in an empty field, _ ___ ____ once 4 is typed — so it is clear what is still asked for. It is never part of the value and screen readers do not announce it; describe the format in the hint for them. It shows wherever a placeholder would: while the field is focused or holds text, and always with label-on-top or without a label. A placeholder replaces the guide — set one to write your own example (placeholder="+358 40 123 4567"); the mask-guide part styles the guide.

Optional sections

A pattern may end in optional sections in square brackets for formats of varying length. Every token inside may be left unfilled, one by one, and the literals inside appear only when a character after them is typed:

<!-- 5 to 12 digits after the country code -->
<c-text-field v-model="phone" label="Phone" mask="+358 #####[#######]" />

<!-- A ZIP code with an optional -#### -->
<c-text-field v-model="zip" label="ZIP code" mask="#####[-####]" />

The field is complete once every token outside the sections is filled, and the guide draws only those: +358 _____ in the empty phone field, nothing once five digits are in. A section may stop part-way (12345-67 is complete), so check the length of unmaskedValue where an all-or-nothing part matters.

Sections come last — after the first one only further sections may follow (## ###[ ####][###]) — and do not nest. A mask that breaks these rules is ignored with a console warning, and the field takes any text. Write \[ and \] for literal brackets.

A phone mask with fixed groups fits only some numbers: Finnish numbers group differently by area code (+358 9 …, +358 40 …), so an ungrouped run like +358 #####[#######] suits them all.

The value is the text as shown, literals included — '+358 40 123 4567'. The read-only unmaskedValue property holds only the characters that fill the tokens ('401234567'). Give the field masked values: a value set from code is shown through the mask, but the field does not rewrite or emit it.

Text that leaves some token unfilled is kept as typed. The read-only maskComplete property tells whether every token is filled, and a field holding such partial text exposes the incomplete custom state. The field shows no error of its own; whether an incomplete value is an error is the consumer's validation, and only a <form> without novalidate stops a submit on it:

<c-text-field
  v-model="phone"
  :error-message="error"
  :invalid="!!error"
  label="Phone"
  mask="+358 ## ### ####"
  @change="
    error = $event.target.matches(':state(incomplete)')
      ? 'Enter the whole number'
      : ''
  "
/>

A mask applies to a single-line field of type text, tel or search; other types (and a textarea) ignore it.

Password managers

A password manager fills only the inputs it can see, and Safari's and Firefox's, like several extensions, do not look inside a component's shadow root. For a username, a password or a one-time code, write the <input> yourself inside the field: it stays in the page, where every password manager finds it, and the field frames it with its label, message and password toggle.

<form action="/login" method="post">
  <c-text-field label="Username">
    <input v-model="username" autocomplete="username" name="username" />
  </c-text-field>

  <c-text-field label="Password">
    <input
      v-model="password"
      autocomplete="current-password"
      name="password"
      type="password"
    />
  </c-text-field>

  <c-button>
    <button type="submit">Log in</button>
  </c-button>
</form>

The input's own attributes apply — type, name, autocomplete, required, disabled, placeholder and the rest — and the field's props of those names are ignored, with a console warning. autocomplete tells the manager what the input holds: username, current-password, new-password (where it offers to generate one) or one-time-code. In a form the input submits and validates itself.

A password manager decides what a form is for — logging in, signing up, changing a password — partly from its submit button, which it cannot find inside a c-button's shadow root: Proton Pass then offers no password to generate on a sign-up form, whatever the page's headings say. Write the submit button yourself inside the c-button, as above: a slotted button, which the c-button paints (see c-button).

The field's value and its value events still work, so v-model goes on the field or on the input. mask, rows and trim-whitespace do not apply to a slotted input.

Examples

Basic
Vue React Angular TypeScript
<template>
  <div>
    <c-text-field
      v-model="name"
      hint="Shown on your public profile"
      label="Display name"
    />

    <p>Value: {{ name }}</p>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const name = ref('');
</script>
Masked
Vue React Angular TypeScript
<template>
  <div>
    <c-text-field
      v-model="phone"
      hint="5–12 digits after the country code"
      label="Phone"
      mask="+358 #####[#######]"
      type="tel"
    />

    <p>Value: {{ phone }}</p>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const phone = ref('');
</script>
Password manager
Vue React Angular TypeScript
<template>
  <form @submit.prevent="loggedIn = username">
    <c-text-field label="Username">
      <input v-model="username" autocomplete="username" name="username" />
    </c-text-field>

    <c-text-field label="Password">
      <input
        v-model="password"
        autocomplete="current-password"
        name="password"
        type="password"
      />
    </c-text-field>

    <!-- The submit button is the page's own too: a password manager reads it
         to tell what the form is for. -->
    <c-button>
      <button type="submit">Log in</button>
    </c-button>

    <p v-if="loggedIn">Logged in as {{ loggedIn }}</p>
  </form>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const username = ref('');

const password = ref('');

const loggedIn = ref('');
</script>
Small
Vue React Angular TypeScript
<template>
  <div style="display: flex; align-items: flex-start; gap: 16px">
    <c-text-field v-model="query" label="Search" size="small" />

    <c-button size="small">Search</c-button>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const query = ref('');
</script>
Textarea
Vue React Angular TypeScript
<template>
  <div>
    <c-text-field
      v-model="description"
      hint="A rows value above 1 renders a textarea"
      label="Description"
      rows="4"
    />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const description = ref('');
</script>

API reference

<c-text-field>

A text field for a single line of text, or several lines under `rows`, with a label, a hint and an error message.

Properties

PropertyAttributeTypeDefaultDescription
autocapitalizeautocapitalizeCTextFieldAutocapitalize— How on-screen keyboards capitalize typed text, as the native `autocapitalize` attribute; unset leaves the browser's default
autocompleteautocompletestring'' The browser's autofill hint, as the native `autocomplete` attribute (`email`, `new-password`, `off`…)
autocorrectautocorrect'off' | 'on' | boolean— Enable native input autocorrection (Safari). Maps to the input's `autocorrect="on"`/`"off"` attribute; left unset (browser default per input type) when not specified. The attribute takes the native values (`autocorrect="off"`), the property also the platform's `HTMLElement.autocorrect` boolean.
autofocusautofocusbooleanfalse Focus the input when the field mounts, as the native `autofocus` does — which is not honoured inside a shadow root.
disableddisabledbooleanfalse Disable the input
errorMessageerror-messagestring'' Error message shown in place of the hint while the input is invalid
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 input
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 input
labelOnToplabel-on-topbooleanfalse app default Label on top of the input
maskmaskstring'' Input mask the typed text follows: `#` a digit, `A` a letter, `*` a letter or a digit, `\` escapes the next character, `[…]` wraps a trailing optional section, anything else is a literal. Applies to a single-line `text`, `tel` or `search` field
maxmaxnull | numbernull Largest value of a `type="number"` field, as the native `max` attribute
minminnull | numbernull Smallest value of a `type="number"` field, as the native `min` attribute
namenamestring'' The name the text submits under in a native `<form>`
placeholderplaceholderstring'' Placeholder of the input. Beside a floating `label` it shows only while the field is focused; under a `mask` it replaces the mask guide
readonlyreadonlybooleanfalse Make the input read-only: its text can be selected and copied but not edited
requiredrequiredbooleanfalse Set the input as required
rowsrowsnumber1 Number of text lines the field shows; above `1` it becomes a multi-line textarea
shadowshadowbooleanfalse app default Draw the field as a raised, drop-shadowed box instead of an outlined one
sizesizeCFieldSize'default' app default Field height: the 52px default (the shared control height) or the 36px `small` box (single-line fields)
stepstepnull | numbernull Step of a `type="number"` field, as the native `step` attribute
trimWhitespacetrim-whitespacebooleanfalse Trim leading and trailing whitespace from the emitted text, and from the shown text when the field is left
typetypeCTextFieldType'text' The native input type: `password` adds a toggle that reveals the text, `date` a button that opens the browser's date picker, and `number` honours `min`, `max` and `step`
valuevaluestring'' The text in the field; under a `mask`, the text as shown, literals included
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
changestringFired when typed text is committed — Enter, or leaving the field after editing it — carrying the text, trimmed when `trim-whitespace` is set.
inputvoidNative bubbling input event fired alongside every value change so a plain Vue `v-model` stays in sync. No detail.
update:valuestringv-model contract event fired on every keystroke, carrying the current text — trimmed when `trim-whitespace` is set.

Methods

MethodSignatureDescription
maskComplete: boolean (read-only)Whether a masked field has every mask token filled (always `true` without a mask)
unmaskedValue: string (read-only)The text without the mask's literals: only the characters filling its tokens (the text as is without a mask)
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
defaultA page's own `<input>`, framed in place of the field's own so that every password manager can fill it; its native attributes are its own
preContent inside the field, before the input, such as an icon
postContent inside the field, after the input and its password or date button

CSS parts

Style from outside with c-text-field::part(name) — parts are the library's only styling customization API.

PartDescription
mask-guideThe faint rest of the input mask, shown behind the typed text
messageThe hint / error message area below the field (always reserved unless `hide-message`)

Custom states

Select on the host's live state with c-text-field:state(name) — combine with ::part() for per-state styling, e.g. c-text-field:state(checked)::part(indicator) targets the indicator only while checked.

StateDescription
incompletePresent while a masked field holds text that leaves a required mask token (one outside an optional section) unfilled

Types

Importable from the package root: import type { … } from '@cscfi/csc-ui'

CTextFieldAutocapitalize

Native `autocapitalize` behaviour of the input.

export type CTextFieldAutocapitalize =
  | 'characters'
  | 'none'
  | 'off'
  | 'on'
  | 'sentences'
  | 'words';
CTextFieldType

Type of the input. `password` gets a reveal toggle, `date` a picker button, `number` honours `min`/`max`/`step`; the rest map straight to the native input type.

export type CTextFieldType =
  | 'date'
  | 'email'
  | 'number'
  | 'password'
  | 'search'
  | 'tel'
  | 'text'
  | 'url';
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';