<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
<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>
<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>
<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>
<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>
<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
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
autocapitalize | autocapitalize | CTextFieldAutocapitalize | — | How on-screen keyboards capitalize typed text, as the native `autocapitalize` attribute; unset leaves the browser's default |
autocomplete | autocomplete | string | '' | The browser's autofill hint, as the native `autocomplete` attribute (`email`, `new-password`, `off`…) |
autocorrect | autocorrect | '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. |
autofocus | autofocus | boolean | false | Focus the input when the field mounts, as the native `autofocus` does — which is not honoured inside a shadow root. |
disabled | disabled | boolean | false | Disable the input |
errorMessage | error-message | string | '' | Error message shown in place of the hint while the input is invalid |
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 input |
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 input |
labelOnTop | label-on-top | boolean | false app default | Label on top of the input |
mask | mask | string | '' | 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 |
max | max | null | number | null | Largest value of a `type="number"` field, as the native `max` attribute |
min | min | null | number | null | Smallest value of a `type="number"` field, as the native `min` attribute |
name | name | string | '' | The name the text submits under in a native `<form>` |
placeholder | placeholder | string | '' | Placeholder of the input. Beside a floating `label` it shows only while the field is focused; under a `mask` it replaces the mask guide |
readonly | readonly | boolean | false | Make the input read-only: its text can be selected and copied but not edited |
required | required | boolean | false | Set the input as required |
rows | rows | number | 1 | Number of text lines the field shows; above `1` it becomes a multi-line textarea |
shadow | shadow | boolean | false app default | Draw the field as a raised, drop-shadowed box instead of an outlined one |
size | size | CFieldSize | 'default' app default | Field height: the 52px default (the shared control height) or the 36px `small` box (single-line fields) |
step | step | null | number | null | Step of a `type="number"` field, as the native `step` attribute |
trimWhitespace | trim-whitespace | boolean | false | Trim leading and trailing whitespace from the emitted text, and from the shown text when the field is left |
type | type | CTextFieldType | '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` |
value | value | string | '' | The text in the field; under a `mask`, the text as shown, literals included |
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 | string | Fired when typed text is committed — Enter, or leaving the field after editing it — carrying the text, trimmed when `trim-whitespace` is set. |
input | void | Native bubbling input event fired alongside every value change so a plain Vue `v-model` stays in sync. No detail. |
update:value | string | v-model contract event fired on every keystroke, carrying the current text — trimmed when `trim-whitespace` is set. |
Methods
| Method | Signature | Description |
|---|---|---|
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): 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 |
|---|---|
default | A 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 |
pre | Content inside the field, before the input, such as an icon |
post | Content 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.
| Part | Description |
|---|---|
mask-guide | The faint rest of the input mask, shown behind the typed text |
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-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.
| State | Description |
|---|---|
incomplete | Present 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';