@fvc/label

@fvc/label provides a form label primitive for FE-VIS applications. It handles required indicators, disabled styling, inline error display, and rendering as any HTML element — covering the full range of label use cases in a form system without requiring additional wrapper components.

Installation

bun add @fvc/label

Peer Dependencies

bun add react antd

Import

import { Label } from '@fvc/label';

Quick Start

import { Label } from '@fvc/label';

export function EmailField() {
  return (
    <>
      <Label htmlFor="email" required>
        Email address
      </Label>
      <input id="email" type="email" />
    </>
  );
}

States

| State | Prop | Visual effect | | --- | --- | --- | | Default | — | Black text (--black-1000), 14px Roboto medium | | Required | required | Appends * after the label text | | Disabled | disabled | Muted colour (--blue-gray-300), not-allowed cursor | | Error | error="message" | Replaces children with the error string; red text (--warning-text-color-800) |

Common Usage

Required field

<Label htmlFor="name" required>Full name</Label>

Disabled

<Label htmlFor="name" disabled>Full name</Label>

Error state

error replaces children. The same element serves as both the label and the inline error message — no separate error component needed.

<Label htmlFor="email" error="Enter a valid email address" />

Combined required and error

<Label htmlFor="email" required error="This field is required" />

Custom element type

When the label is not semantically a <label> element, pass elementType. The htmlFor attribute is omitted automatically when elementType is not 'label'.

<Label elementType="span">Section heading</Label>
<Label elementType="p">Description text</Label>

Props

| Prop | Type | Default | Description | | --- | --- | --- | --- | | children | ReactNode | — | Label text. Replaced by error when error is provided. | | htmlFor | string | — | Native htmlFor attribute. Only applied when elementType is 'label'. | | for | string | — | Alias for htmlFor. | | required | boolean | false | Appends a * indicator after the content. | | disabled | boolean | false | Applies disabled styling. | | error | string | — | Replaces children and applies error colour when set. | | elementType | ElementType | 'label' | Renders the label as any HTML or React element. | | testId | string | — | Maps to data-testid. | | className | string | — | Additional CSS class names. |

All standard HTMLAttributes<HTMLElement> are accepted and forwarded to the root element.

Consumer Example

import { Label } from '@fvc/label';
import { Input } from 'antd';
import { ReactNode } from 'react';

interface FormFieldProps {
  id: string;
  label: string;
  required?: boolean;
  disabled?: boolean;
  error?: string;
  children: ReactNode;
}

export function FormField({
  id,
  label,
  required,
  disabled,
  error,
  children,
}: FormFieldProps) {
  return (
    <div>
      <Label htmlFor={id} required={required} disabled={disabled} error={error}>
        {label}
      </Label>
      {children}
    </div>
  );
}

Testing

Use testId when a stable test selector is needed.

<Label testId="email-label" htmlFor="email">Email address</Label>

screen.getByTestId('email-label');

CSS Classes

| Class | Applied when | | --- | --- | | .fvc-label | Always — base class | | .fvc-label-error | error prop is a non-empty string | | .fvc-label-disabled | disabled is true |

Customisation

@fvc/label exposes a CSS-customisation API via CSS custom properties declared in variables.scss. Override any variable in your own stylesheet to re-style the component without touching source or shipping a fork.

:root {
  --label-default-color: #1a1a2e;
  --label-error-color: #dc2626;
  --label-disabled-color: #94a3b8;
  --label-md-size-fz: 13px;
  --label-font-family: 'Inter', sans-serif;
}

Variables

| Variable | Default | Description | | --- | --- | --- | | --label-font-family | 'Roboto', sans-serif | Font family for all label states | | --label-md-size-fz | 14px | Font size | | --label-md-size-fw | 500 | Font weight | | --label-md-size-lh | 16px | Line height | | --label-md-size-margin | 6px | Bottom margin (space between label and the field below) | | --label-default-color | var(--black-1000) | Text color in the default state | | --label-error-color | var(--warning-text-color-800) | Text color in the error state | | --label-disabled-color | var(--blue-gray-300) | Text color in the disabled state |

Development

bun run lint
bun run type-check
bun run test