FloatLabel
A standalone label that moves onto the input border when the field has a value, receives focus, or opens a panel.
Import
ts
import { NsFloatLabel, NsInput } from '@ns/ui'
import type { FloatLabelProps } from '@ns/ui'
Examples
Basic Usage
vue
<script setup lang="ts">
import { ref } from 'vue'
import { NsFloatLabel, NsInput } from '@ns/ui'
const name = ref('')
</script>
<template>
<NsFloatLabel label="Department" style="width: 260px; margin-top: 8px">
<NsInput v-model="name" clearable />
</NsFloatLabel>
</template>
Input Controls
vue
<script setup lang="ts">
import { reactive } from 'vue'
import {
NsFloatLabel,
NsInput,
NsTextarea,
NsSelect,
NsCascader,
NsTreeSelect,
NsTimePicker,
NsDatePicker,
NsAutoComplete,
NsInputTag,
NsMentions,
NsIconPicker
} from '@ns/ui'
const model = reactive({
name: '',
remark: '',
department: undefined as string | undefined,
region: [] as string[],
tree: undefined as string | undefined,
time: '',
date: '',
keyword: '',
tags: [] as string[],
mentions: '',
icon: ''
})
const options = [
{ label: 'Engineering', value: 'dev' },
{ label: 'Operations', value: 'ops' }
]
const regions = [{ label: 'East', value: 'east', children: [{ label: 'Shanghai', value: 'sh' }] }]
const tree = [
{ label: 'Head office', id: 'root', children: [{ label: 'Engineering', id: 'dev' }] }
]
</script>
<template>
<div class="float-grid">
<NsFloatLabel label="Input"><NsInput v-model="model.name" clearable /></NsFloatLabel>
<NsFloatLabel label="Textarea"><NsTextarea v-model="model.remark" /></NsFloatLabel>
<NsFloatLabel label="Select"
><NsSelect v-model="model.department" :options="options" clearable
/></NsFloatLabel>
<NsFloatLabel label="Cascader"
><NsCascader v-model="model.region" :options="regions"
/></NsFloatLabel>
<NsFloatLabel label="TreeSelect"
><NsTreeSelect v-model="model.tree" :data="tree"
/></NsFloatLabel>
<NsFloatLabel label="TimePicker"><NsTimePicker v-model="model.time" /></NsFloatLabel>
<NsFloatLabel label="DatePicker"><NsDatePicker v-model="model.date" /></NsFloatLabel>
<NsFloatLabel label="AutoComplete"
><NsAutoComplete v-model="model.keyword" :options="options"
/></NsFloatLabel>
<NsFloatLabel label="InputTag"><NsInputTag v-model="model.tags" /></NsFloatLabel>
<NsFloatLabel label="Mentions"
><NsMentions v-model="model.mentions" :options="options"
/></NsFloatLabel>
<NsFloatLabel label="IconPicker"><NsIconPicker v-model="model.icon" /></NsFloatLabel>
</div>
</template>
<style scoped>
.float-grid {
display: grid;
grid-template-columns: repeat(2, minmax(0, 1fr));
gap: 24px;
padding-top: 8px;
}
@media (max-width: 600px) {
.float-grid {
grid-template-columns: minmax(0, 1fr);
}
}
</style>
Labels That Stay Raised
Number controls, date ranges, and fields with leading content keep their labels raised.
vue
<script setup lang="ts">
import { ref } from 'vue'
import { NsFloatLabel, NsInputNumber, NsDatePicker, NsInput, NsSpace } from '@ns/ui'
const count = ref<number | undefined>()
const range = ref<[string, string]>(['', ''])
const keyword = ref('')
</script>
<template>
<NsSpace wrap align="start" size="large" style="padding-top: 8px">
<NsFloatLabel label="Quantity" style="width: 200px"
><NsInputNumber v-model="count"
/></NsFloatLabel>
<NsFloatLabel label="Date range" style="width: 300px"
><NsDatePicker v-model="range" type="daterange"
/></NsFloatLabel>
<NsFloatLabel label="Search" style="width: 240px"
><NsInput v-model="keyword" prefix-icon="search"
/></NsFloatLabel>
</NsSpace>
</template>
Sizes
vue
<script setup lang="ts">
import { reactive } from 'vue'
import { NsFloatLabel, NsInput, NsSpace } from '@ns/ui'
const sizes = ['large', 'default', 'small'] as const
const model = reactive({ large: '', default: '', small: '' })
</script>
<template>
<NsSpace direction="vertical" fill size="large" style="padding-top: 8px">
<NsFloatLabel v-for="size in sizes" :key="size" :label="size" style="width: 260px">
<NsInput v-model="model[size]" :size="size" />
</NsFloatLabel>
</NsSpace>
</template>
Toolbar
vue
<script setup lang="ts">
import { ref } from 'vue'
import { NsFloatLabel, NsInput, NsSelect, NsButton, NsMessage, NsSpace } from '@ns/ui'
const name = ref('')
const status = ref<string>()
const options = [
{ label: 'Enabled', value: 'enabled' },
{ label: 'Disabled', value: 'disabled' }
]
const search = () =>
NsMessage.info(`Search: ${name.value || 'all names'}, ${status.value || 'all statuses'}`)
</script>
<template>
<NsSpace wrap align="center" style="padding-top: 8px">
<NsFloatLabel label="Name" style="width: 220px"
><NsInput v-model="name" clearable
/></NsFloatLabel>
<NsFloatLabel label="Status" style="width: 180px"
><NsSelect v-model="status" :options="options" clearable
/></NsFloatLabel>
<NsButton type="primary" icon="search" @click="search">Search</NsButton>
</NsSpace>
</template>
Disabled
vue
<script setup lang="ts">
import { NsFloatLabel, NsInput, NsSelect, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace wrap size="large" style="padding-top: 8px">
<NsFloatLabel label="Empty" style="width: 240px"><NsInput disabled /></NsFloatLabel>
<NsFloatLabel label="Filled" style="width: 240px"
><NsInput model-value="Engineering" disabled
/></NsFloatLabel>
<NsFloatLabel label="Select" style="width: 240px"
><NsSelect disabled :options="[]"
/></NsFloatLabel>
</NsSpace>
</template>
Explicit Validation State
vue
<script setup lang="ts">
import { ref } from 'vue'
import { NsFloatLabel, NsInput, NsSwitch, NsSpace } from '@ns/ui'
const invalid = ref(true)
const name = ref('')
</script>
<template>
<NsSpace direction="vertical" fill size="large">
<NsSwitch v-model="invalid" aria-label="Invalid" />
<NsFloatLabel label="Department" :invalid="invalid" style="width: 260px; margin-top: 8px">
<NsInput v-model="name" />
</NsFloatLabel>
</NsSpace>
</template>
Form Validation
Leave the enclosing form item's label unset. It still displays errors and connects them to the field.
vue
<script setup lang="ts">
import { reactive, ref } from 'vue'
import { NsFloatLabel, NsInput, NsForm, NsFormItem, NsButton, NsMessage, NsSpace } from '@ns/ui'
const model = reactive({ name: '' })
const form = ref<InstanceType<typeof NsForm>>()
const rules = {
name: [{ required: true, message: 'Enter a department', trigger: 'blur' as const }]
}
const validate = async () => {
const result = await form.value?.validate()
if (result?.valid) NsMessage.success('Validation passed')
}
</script>
<template>
<NsForm ref="form" :model="model" :rules="rules" label-width="0" style="padding-top: 8px">
<NsFormItem prop="name">
<NsFloatLabel label="Department" style="width: 260px"
><NsInput v-model="model.name"
/></NsFloatLabel>
</NsFormItem>
<NsSpace><NsButton type="primary" @click="validate">Validate</NsButton></NsSpace>
</NsForm>
</template>
Custom Label
vue
<script setup lang="ts">
import { ref } from 'vue'
import { NsFloatLabel, NsInput, NsIcon } from '@ns/ui'
const name = ref('')
</script>
<template>
<NsFloatLabel style="width: 260px; margin-top: 8px">
<template #label><NsIcon name="user" size="inherit" /> Contact *</template>
<NsInput v-model="name" />
</NsFloatLabel>
</template>
Manual Filled State And Native Input
filled overrides automatic detection. A native input does not register itself; its label is placed above it, and its accessible name must be supplied explicitly.
vue
<script setup lang="ts">
import { ref } from 'vue'
import { NsFloatLabel, NsInput, NsSwitch, NsSpace } from '@ns/ui'
const filled = ref(false)
const nativeValue = ref('')
</script>
<template>
<NsSpace direction="vertical" fill size="large">
<NsSwitch v-model="filled" aria-label="Raise label" />
<NsFloatLabel label="Manual state" :filled="filled" style="width: 260px; margin-top: 8px"
><NsInput
/></NsFloatLabel>
<NsFloatLabel label="Native input" :filled="nativeValue !== ''" style="width: 260px">
<input v-model="nativeValue" aria-label="Native input" />
</NsFloatLabel>
</NsSpace>
</template>
Placeholder
vue
<script setup lang="ts">
import { ref } from 'vue'
import { NsFloatLabel, NsInput } from '@ns/ui'
const name = ref('')
</script>
<template>
<NsFloatLabel label="Department" style="width: 260px; margin-top: 8px">
<NsInput v-model="name" placeholder="For example: Engineering" clearable />
</NsFloatLabel>
</template>
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| label | string | — | Label text; the label slot takes priority |
| filled | boolean | undefined | Explicit filled state; otherwise detected from the field, or raised when unknown |
| invalid | boolean | undefined | Explicit label error state; otherwise follows the form item |
Events
None.
Slots
| Slot | Description |
|---|---|
| default | One input control |
| label | Custom label content |
Methods
None.
Types
ts
interface FloatLabelProps {
label?: string
filled?: boolean
invalid?: boolean
}
Notes
- Only the first field is associated. Additional fields trigger a development warning.
null,undefined, empty strings, empty arrays, and arrays containing only empty values are empty.0andfalsecount as filled.- Size follows the field, form item, form, then global configuration. FloatLabel has no independent
sizeprop. - Number inputs, date ranges, and inputs with leading content keep labels raised. Checkboxes, switches, and unsupported field structures use a label above the control.
- Leave at least 8px above the label to avoid clipping.
- Forms can use
label-position="float"directly. When using FloatLabel inside a form item, omit the form item'slabeland uselabel-width="0"when no label column is needed. invalidchanges label color only. It does not run validation or override the field'saria-invalid.- For native or custom inputs, provide the value state and accessible name yourself. Use
filledto pass value state. An absent label does not hide the field's placeholder. - The raised label uses
--ns-bg-colorto mask a short section of the border. Match this variable to the surrounding background.