Input

SInput is a text field with a label, a hint, an error state and correct a11y wiring (label, aria-describedby, aria-invalid). It works through v-model. The use-tags flag turns it into a tags input (see below).

Basic usage

Name

<template>
  <SInput
    v-model="name"
    label="Name"
    placeholder="Enter your name"
  />
</template>

Square corners

The square prop removes the rounding of the field border (fields are rounded by default). Available on all fields.

Rounded

Square

<template>
  <SInput
    square
    label="Square"
    placeholder="square"
  />
</template>

Floating label

By default the label floats: at rest it looks like a placeholder inside the border, and on focus or once filled it moves up onto the top border with a notch cut into it. The label size is fixed and does not depend on size. Turn it off with :floating-label="false" — the label then renders as a regular line above the field.

Floating (default)

Regular label

<template>
  <SInput label="Floating (default)" />
  <SInput
    label="Regular label"
    :floating-label="false"
  />
</template>

Hint and error

Email

Your work email

Email

This field is required

<template>
  <SInput
    label="Email"
    hint="Your work email"
  />
  <SInput
    label="Email"
    error="This field is required"
  />
</template>

Sizes

The size prop (sm/md/lg) controls padding and font size.

sm

md

lg

<template>
  <SInput
    label="sm"
    size="sm"
  />
  <SInput
    label="md"
    size="md"
  />
  <SInput
    label="lg"
    size="lg"
  />
</template>

Icons and clearing

icon draws a leading icon (a name from the registry — here a custom search icon registered with registerIcons). The clearable flag adds a clear button, visible while the value is not empty.

Clearable

<script setup lang="ts">
import { ref } from 'vue'
import { registerIcons } from '@smalt-ui/core'

registerIcons({
  search: [
    ['circle', { cx: 11, cy: 11, r: 8 }],
    ['path', { d: 'm21 21-4.3-4.3' }],
  ],
})

const query = ref('Draft report')
</script>

<template>
  <SInput
    icon="search"
    placeholder="Search"
    aria-label="Search"
  />
  <SInput
    v-model="query"
    clearable
    label="Clearable"
  />
</template>

prepend / append slots

The prepend and append slots put arbitrary content inside the field border — an icon, text or a button. Unlike the decorative icon prop, slot content is interactive.

$

<template>
  <SInput
    placeholder="0.00"
    aria-label="Amount"
  >
    <template #prepend>
      <span>$</span>
    </template>
  </SInput>

  <SInput
    placeholder="Value"
    aria-label="Value"
  >
    <template #append>
      <SButton
        size="sm"
        variant="ghost"
        icon="copy"
        aria-label="Copy"
      />
    </template>
  </SInput>
</template>

States

disabled blocks input, invalid marks the field as invalid (in addition to error), required adds * to the label and sets the native required attribute.

Disabled

Invalid

Required *

<template>
  <SInput
    label="Disabled"
    disabled
    placeholder="Unavailable"
  />
  <SInput
    label="Invalid"
    invalid
    placeholder="Check the value"
  />
  <SInput
    label="Required"
    required
    placeholder="Fill in the field"
  />
</template>

Input types

The type prop is the native <input> type: password (masks input), email (email keyboard and validation), and so on.

Password

Email

<template>
  <SInput
    label="Password"
    type="password"
    placeholder="••••••••"
  />
  <SInput
    label="Email"
    type="email"
    placeholder="you@company.com"
  />
</template>

type="number" never reaches the DOM

On intermediate invalid input, a native number field hands the browser an empty string: typing 12,75 can turn into 5 while the field stays empty — the value gets corrupted silently. That is why type="number" enables numeric mode (see below) and renders as text.

Numeric mode

The numeric prop restricts input to a number: letters and a second decimal separator simply never appear in the field, rather than being removed after typing. true means integers; an object sets precision and bounds. v-model holds a normalized string (dot as the decimal separator, no group separators), so Number(value) always works, while the field shows the locale's usual formatting.

It also sets inputmode, so phones open a numeric keyboard.

Quantity

pcs

Weight

kg

Declared value

$

<template>
  <SInput
    v-model="count"
    label="Quantity"
    numeric
    suffix="pcs"
  />
  <SInput
    v-model="weight"
    label="Weight"
    :numeric="{ decimals: 2, unsigned: true }"
    suffix="kg"
  />
  <SInput
    v-model="value"
    label="Declared value"
    :numeric="{ decimals: 2, unsigned: true, max: 100000 }"
    suffix="$"
  />
</template>

Key	What it does
decimals	digits after the separator; 0 (default) allows integers only
unsigned	disallows the minus sign
min/max	value bounds — applied on change, not on every keystroke
locale	formatting locale, en by default

Bounds are checked on the change event on purpose: if they were applied on every keystroke, with min: 10 you could not type the first digit — it would immediately be replaced with 10.

For a field with a stepper — "minus" and "plus" buttons — there is a separate SNumberField.

Units

The prefix and suffix props draw text inside the border, before and after the input: units of measure, a currency sign, a country code. Unlike the prepend/append slots, they do not intercept clicks — tapping next to the unit moves focus into the field.

Weight

kg

Amount

$

Phone

+1

<template>
  <SInput
    label="Weight"
    suffix="kg"
  />
  <SInput
    label="Amount"
    prefix="$"
  />
</template>

Read-only

readonly keeps the value visible and selectable but not editable. Unlike disabled, the field is not dimmed, stays in the tab order and is submitted with the form; the clear button is hidden.

Order number

Order number

<template>
  <SInput
    v-model="orderId"
    label="Order number"
    readonly
  />
</template>

Native attributes and events

Everything not declared as a prop goes to the <input> itself: maxlength, autocomplete, name, pattern, @blur, @focus, @change handlers. Only class and style stay on the outer border.

<template>
  <SInput
    v-model="zip"
    label="ZIP code"
    name="postal-code"
    autocomplete="postal-code"
    maxlength="5"
    class="own-class"
    @blur="validate"
  />
</template>

This matters for @blur: the event does not bubble, so the handler has to sit on the field itself. Attached to the outer div, it would silently never fire.

Trailing icon and custom clear icon

iconRight draws a decorative icon on the right inside the field; clearIcon sets a custom icon for the clear button (instead of the default cross).

Email

Custom clear icon

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

const query = ref('Draft report')
</script>

<template>
  <SInput
    label="Email"
    icon-right="mail"
    placeholder="you@company.com"
  />
  <SInput
    v-model="query"
    clearable
    clear-icon="trash-2"
    label="Custom clear icon"
  />
</template>

Input mask

The mask prop formats input by a template of tokens; the fill-mask flag shows the template in the field and keeps it visible while typing (__/__/____). Tokens, named masks and options are listed in the API table below.

(___) ___ - ____

Phone

____ ____ ____ ____

Card

__/__/____

Date of birth

<template>
  <SInput
    v-model="phone"
    label="Phone"
    mask="(###) ### - ####"
    fill-mask
  >
    <template #prepend>
      <SIcon
        icon="phone"
        :size="16"
      />
    </template>
  </SInput>
  <SInput
    v-model="card"
    label="Card"
    mask="card"
    fill-mask
  >
    <template #prepend>
      <SIcon
        icon="credit-card"
        :size="16"
      />
    </template>
  </SInput>
  <SInput
    v-model="birth"
    label="Date of birth"
    mask="##/##/####"
    fill-mask
  >
    <template #prepend>
      <SIcon
        icon="calendar"
        :size="16"
      />
    </template>
  </SInput>
</template>

Raw value and letters

With unmasked-value, v-model receives the value without separators (handy for sending to the backend). Letter tokens with a case transform suit IDs such as a license number: AA ###### (letters are uppercased).

(___) ___ - ____

Phone (raw value)

v-model: —

__ ______

License number

Letters are uppercased

<script setup>
import { ref } from 'vue'
const rawPhone = ref('')
const license = ref('')
</script>

<template>
  <!-- v-model receives "9991234567" instead of "(999) 123 - 4567" -->
  <SInput
    v-model="rawPhone"
    label="Phone (raw value)"
    mask="phone"
    fill-mask
    unmasked-value
  >
    <template #prepend>
      <SIcon
        icon="phone"
        :size="16"
      />
    </template>
  </SInput>
  <!-- The A token forces letters to uppercase -->
  <SInput
    v-model="license"
    label="License number"
    mask="AA ######"
    fill-mask
  >
    <template #prepend>
      <SIcon
        icon="file-text"
        :size="16"
      />
    </template>
  </SInput>
</template>

Tags mode (use-tags)

The use-tags flag enables entering multiple tags (it replaces the former standalone STagsInput component). In this mode v-model is a string[]: a new tag is added on Enter, and each tag is an STag chip with a remove button. The duplicate, add-on-paste and max props control input behavior.

Technologies

Vue

Nuxt

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

const stack = ref(['Vue', 'Nuxt'])
</script>

<template>
  <SInput
    v-model="stack"
    use-tags
    label="Technologies"
    placeholder="Type and press Enter"
    :max="5"
  />
</template>

API

Props

Name	Type	Default	Description
id	string	undefined	Input id. Generated automatically when not set (SSR-safe).
type	string	"text"	Type of the native input (plain mode only, not use-tags). number never reaches the DOM: on intermediate invalid input the browser returns an empty string and silently loses what was typed, so numeric mode is enabled instead, see numeric.
label	string	undefined	Field label (linked to the input via for/id).
floating-label	boolean	true	Floating label: the label sits inside the border, looks like a placeholder at rest and floats up to the top edge on focus or when filled. On by default; false renders a regular label above the field. The label size is fixed and does not depend on size.
hint	string	undefined	Hint below the field.
error	string	undefined	Error message. When set, the field is marked invalid.
placeholder	string	undefined	Placeholder text in an empty field.
size	"md" | "sm" | "lg"	"md"	Field size: sm (32px), md (40px) or lg (48px).
disabled	boolean	false	Disables input and makes the field inactive.
required	boolean	false	Marks the field as required: adds * to the label and sets required.
invalid	boolean	false	Explicitly marks the field invalid (in addition to error).
readonly	boolean	undefined	Read-only field: the value is visible and selectable but cannot be edited.
square	boolean	undefined	Square corners: removes the field border radius (rounded by default).
prefix	string	undefined	Text prefix inside the border, before the input (e.g. $, +1).
suffix	string	undefined	Text suffix inside the border, after the input: a unit of measure (kg, cm, pcs).
icon	string	undefined	Registry name or raw path of the leading icon, drawn on the left inside the field.
icon-right	string	undefined	Registry name or raw path of the trailing icon, drawn on the right (plain mode only).
clearable	boolean	false	Shows a clear button that resets the field value (plain mode only).
clear-icon	string	"x"	Registry name or raw path of the clear button icon.
clear-label	string	undefined	Accessible name of the clear button (defaults to the locale dictionary).
mask	string	undefined	Input mask (plain mode only, not use-tags). A pattern of tokens: # is a digit, S a letter, N alphanumeric, A/a an upper/lowercase letter, X/x upper/lowercase alphanumeric; any other character is a literal separator. Escape a literal with \ (e.g. \#). Named masks are supported: phone, date, datetime, time, fulltime, card. Example: mask="(###) ### - ####".
unmasked-value	boolean	false	With a mask: v-model holds the raw value without separators/literals (e.g. 9991234567 instead of (999) 123 - 4567). By default the model contains the masked string.
fill-mask	string | false | true	undefined	With a mask: shows the mask template right in the field, with empty slots filled by a character that **stays visible while typing** (e.g. (123) 45_ - ____). true uses _; a string sets a custom character (e.g. fill-mask="·"). Drawn as a "ghost" layer behind the text, so the caret works natively. The label stays floated at the top.
numeric	| false | true | { decimals?: number; unsigned?: boolean; min?: number; max?: number; locale?: string }	undefined	Numeric mode (plain mode only, not use-tags; incompatible with mask). true allows integers; an object sets precision and bounds. v-model holds a normalized string: a dot as the decimal separator and no group separators, so Number(value) always works. Example: :numeric="{ decimals: 2, unsigned: true, max: 1000 }".
use-tags	boolean	false	Tags mode: the field becomes an input for multiple tags. In this mode modelValue is a string[] rather than a string; the type/iconRight/clearable props do not apply.
duplicate	boolean	false	Tags mode: allows duplicate tags.
add-on-paste	boolean	true	Tags mode: adds tags when pasting from the clipboard (split by the delimiter).
max	number	undefined	Tags mode: maximum number of tags.
remove-icon	string	"x"	Tags mode: icon of the tag remove button (registry name or raw path).
remove-tag-label	string	undefined	Tags mode: accessible name of the tag remove button (defaults to the locale dictionary).
model-value	string | string[]	undefined	Field value: string in regular mode, string[] (the tag list) with use-tags. Two-way bound via v-model.

Events

Name	Signature	Description
update:modelValue	( value: | string | string[] | undefined ) => void	Emitted when modelValue changes. Used for two-way binding (v-model).

Slots

Name	Description
prepend	Content at the start of the field, inside the border (icon, button).
append	Content at the end of the field, inside the border (icon, button).