# Label

> A field's visible label in the label type Variant, with a required marker read as "required".

Component · forms. Registry item `label`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/label.json

## Installation

```sh
npx nativecn-cli@latest add label
```

Also installs: [theme](https://nativecn.dev/docs/theme/theme), [text](https://nativecn.dev/docs/components/text).

## Usage

### Label demo

A Label and a required Label.

```tsx
import { View } from "react-native";

import { Label } from "@/components/label";

export function LabelDemo() {
  return (
    <View>
      <Label>Display name</Label>
      <Label required>Email</Label>
    </View>
  );
}
```

## Props

| Prop | Type and description |
|---|---|
| `children` | ReactNode: the label text |
| `required` | boolean: shows * and adds "required" to the spoken name (default false) |
| `style` | TextStyle, merged last |

## Accessibility

- With required and string children it is read as "<text>, required"; the * marker is hidden from screen readers.
- Inside a FormField the visible label is hidden from screen readers; the control reads it as its name instead.
- It uses the label text Variant, which caps the OS font scale at 1.5× when font scaling is on.

## Notes

Inside a FormField the label is drawn by FormField and read as the control's name; use Label on its own only next to custom controls. Text props pass through.

## Source

### {components}/label.tsx

```tsx
import type { ReactNode } from "react";

import { Text, type TextProps } from "@/components/text";

export type LabelProps = Omit<TextProps, "variant" | "color"> & {
  /** The label text. */
  children?: ReactNode;
  /** Shows a required marker (*) after the text; screen readers hear "required" instead. */
  required?: boolean;
};

/**
 * A field's visible label: the `label` text Variant, with an optional required marker. Inside a
 * FormField the label is drawn by FormField itself and read as the control's name, so use Label
 * on its own only next to custom controls. `style` is merged last.
 */
export function Label({
  children,
  required = false,
  "aria-label": ariaLabel,
  ...props
}: LabelProps) {
  const name =
    ariaLabel ?? (required && typeof children === "string" ? `${children}, required` : undefined);
  return (
    <Text variant="label" aria-label={name} {...props}>
      {children}
      {required ? (
        <Text variant="label" color="destructive" aria-hidden>
          {" *"}
        </Text>
      ) : null}
    </Text>
  );
}
```