Label

Overview

VyLabel renders styled text for a form control. It supports four text sizes, a visual required marker, a control identifier, and local or global theme overrides.

Usage

<script setup lang="ts">
import { ref } from 'vue'
import { VyInput, VyLabel } from '@vyui/kit'

const name = ref('')
</script>

<template>
  <view class="flex flex-col gap-2">
    <VyLabel for="display-name">Display name</VyLabel>
    <VyInput
      id="display-name"
      v-model="name"
      placeholder="Ada Lovelace"
    />
  </view>
</template>

Use short, specific text that describes the value a user should enter or change.

Required

Set required to append the theme's visual asterisk.

<template>
  <view class="flex flex-col gap-2">
    <VyLabel for="email" required>Email address</VyLabel>
    <VyInput id="email" type="email" placeholder="you@example.com" />
    <text class="text-xs text-neutral-500">Required for account recovery.</text>
  </view>
</template>

The marker is presentational. Set required or validation state on the control separately and provide a visible error message when validation fails.

Size

Choose a size that matches the control and surrounding hierarchy.

<template>
  <view class="flex flex-col gap-3">
    <VyLabel size="sm">Small label</VyLabel>
    <VyLabel size="md">Default label</VyLabel>
    <VyLabel size="lg">Large label</VyLabel>
    <VyLabel size="xl">Extra-large label</VyLabel>
  </view>
</template>

Custom content

The default slot accepts any renderable content, although concise text is the clearest form label.

<VyLabel for="workspace-name">
  <view class="flex flex-row items-center gap-2">
    <text>Workspace name</text>
    <VyBadge label="Public" color="info" size="sm" />
  </view>
</VyLabel>

When using a nested layout, verify that its text styles and wrapping remain legible at larger accessibility text sizes.

Features and behavior

• Renders the @vyui/core Label primitive as a Lynx text element by default.
• for is forwarded to the rendered element.
• required changes only the theme and does not update the associated control.
• The default slot is the only content API.
• class and ui.base are merged with the resolved theme classes.

Props

Emits

This component does not emit events.

Slots

Styling and theming

Override globally through appConfig.ui.label or locally with ui.

Theme variants

The base theme uses medium-weight, non-selectable, dark gray text. Override ui.base when a denser form needs smaller typography than the built-in scale.

Accessibility

Always keep the label visible; a placeholder is not a replacement because it disappears after entry and may be read inconsistently. Put units or formatting guidance in nearby help text rather than overloading the label.

The current primitive forwards for as an attribute on a Lynx text element, but it does not implement native label-to-control activation or accessible-name association. Tapping VyLabel does not focus the referenced control. Verify the control's accessible name with VoiceOver and TalkBack, and attach native accessibility attributes directly to the control when required.

required is visual only and does not announce required state. Set the control's own required semantics where supported, explain the requirement in text, and do not rely on the red asterisk or color alone.

Platform notes

• The component renders a Lynx text primitive, not a DOM <label>.
• The for and matching control id are useful identifiers but do not currently create native focus behavior.
• The required marker uses an after: pseudo-element utility from the kit theme; verify custom Lynx styling pipelines preserve that utility.
• The theme uses logical margin (ms) for the marker so spacing follows writing direction.
• select-none prevents accidental text selection in supported targets.

Related components

• NumberField for bounded numeric entry.
• Input and Textarea for text entry.
• FormField for integrated label, description, hint, help, and validation layout.