# Label

Labels give a name to a component or group of components.

## Best practices

### Do

- Pair the label with the component or group it names.
- Use an asterisk to identify required information.
- Keep label text brief and use sentence-style capitalization.

### Don't

- Use placeholder text in place of a label.
- Truncate long labels; allow them to wrap.
- Add end punctuation unless the label is a question.
- Put a colon after a label.

## Behavior and states

- A label can display a disabled state if the component it names is also disabled.
- If a label is longer than its container, the text wraps onto the next line.
- Labels never truncate.
- Pair them with components like checkboxes and inputs to prompt someone to enter certain information, or with plaintext to categorize information.
- If you need a label with an info button, consider InfoLabel.
- If you are are combining Label, any form component and need helper text and validation, consider Field.

## Default

Source: CoreAI.

[Download source](/coreai-design-system/source/examples/components-label--default.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import type { LabelProps } from "@coreai-ds/react-components";
import type { JSXElement } from "@coreai-ds/react-components";
import { Label } from "@coreai-ds/react-components";
import * as React from 'react';

export const Default = (props: LabelProps): JSXElement => <Label {...props}>This is a label</Label>;

export default Default;
```

## API

Generated CoreAI prop summaries, not replacement type declarations. Most native DOM/event and ARIA props are omitted. `?` means optional; JSDoc shows defaults, deprecations, and conditional requirements. Defaults assume the standard CoreAI provider.

### Label API

A label component provides a title or name to a component.

```ts
interface LabelProps {
  as?: "label";

  children?: any;

  className?: string;

  /**
   * Renders the label as disabled
   * @default false
   */
  disabled?: boolean;

  ref?: Ref<HTMLLabelElement>;

  /**
   * Displays an indicator that the label is for a required field. The required prop can be set to true to display
   * an asterisk (*). Or it can be set to a string or jsx content to display a different indicator.
   * @default false
   */
  required?: boolean | WithSlotShorthandValue<{ as?: "span"; } & Omit<Omit<DetailedHTMLProps<HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, "ref"> & { ref?: ((instance: HTMLSpanElement | null) => void) | RefObject<HTMLSpanElement> | null; }, "children"> & { children?: any; }> | null | undefined;

  /**
   * A label supports different sizes.
   * @default 'medium'
   */
  size?: "small" | "medium" | "large";

  style?: CSSProperties;

  /**
   * A label supports regular and semibold fontweight.
   * @default regular
   */
  weight?: "regular" | "semibold";
}
```

## Implementation

CoreAI 0.12.0; Fluent 9.74.9.

[Setup and dependencies](/coreai-design-system/guides/Package.md).

Import components from `@coreai-ds/react-components`. CoreAI guidance above takes precedence over API demonstration examples.

Note: Storybook-only layout decorators are omitted. Examples use the documentation preview spacing instead.

## Disabled

Source: Fluent, adapted for CoreAI.

A Label can be disabled.
Since this state does not meet the required accessibility contrast ratio,
      it should be used sparingly and make it clear that there's no interaction with the
      control associated with it.

[Download source](/coreai-design-system/source/examples/components-label--disabled.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import type { JSXElement } from "@coreai-ds/react-components";
import { Label } from "@coreai-ds/react-components";
import * as React from 'react';

export const Disabled = (): JSXElement => (<Label disabled required>
    Disabled label
  </Label>);

export default Disabled;
```

## Required

Source: Fluent, adapted for CoreAI.

A Label can display a required asterisk or a custom required indicator. This custom required indicator canbe a custom string or jsx content.

[Download source](/coreai-design-system/source/examples/components-label--required.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import type { JSXElement } from "@coreai-ds/react-components";
import { Label } from "@coreai-ds/react-components";
import * as React from 'react';

export const Required = (): JSXElement => (<>
    <Label required>Required label</Label>
    <Label required="***">Required label</Label>
  </>);

export default Required;
```

## Size

Source: Fluent, adapted for CoreAI.

A Label supports `small`, `medium`, and `large` sizes.

[Download source](/coreai-design-system/source/examples/components-label--size.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import type { JSXElement } from "@coreai-ds/react-components";
import { Label } from "@coreai-ds/react-components";
import * as React from 'react';

export const Size = (): JSXElement => {
    return (<>
      <Label size="small">Small</Label>
      <Label size="medium">Medium</Label>
      <Label size="large">Large</Label>
    </>);
};

export default Size;
```

## Weight

Source: Fluent, adapted for CoreAI.

A Label with a semibold font weight.

[Download source](/coreai-design-system/source/examples/components-label--weight.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import type { JSXElement } from "@coreai-ds/react-components";
import { Label } from "@coreai-ds/react-components";
import * as React from 'react';

export const Weight = (): JSXElement => <Label weight="semibold">Strong label</Label>;

export default Weight;
```

## Resources

- [Figma component](https://www.figma.com/design/eXfSQrRg3poHRgmr0ivN5V/CoreAI-Figma-Library?node-id=7062-121104)
- [Fluent guidance](https://fluent2.microsoft.design/components/web/react/core/label/usage)