# Text

Typography primitive for consistent, standardized text styling.

## Default

Source: CoreAI.

A typical mix of `Text` usages in one piece of content: a heading, a body
paragraph, a bold callout, an inline code reference, and small metadata —
each combining a `preset` (size/weight) with a `foreground` emphasis level
appropriate to its role. Explicit props like `weight="bold"` still override
`preset`'s defaults, as shown on the callout line. Nested text inherits every
unset typography property: the date changes only foreground, while inline
code changes only font family and foreground.

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

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

import * as React from 'react';
import { Text } from "@coreai-ds/react-components";
import { Divider } from "@coreai-ds/react-components";

export const Default = () => {
    /** Renders inline code-styled text using `Text`'s `monospace` font. */
    const Code = ({ children }: React.PropsWithChildren): React.JSX.Element => (<Text font="monospace" foreground={1}>
        {children}
      </Text>);
    const styles = /* css */ `
      .text-default-example {
        display: flex;
        flex-direction: column;
        align-items: flex-start;
        gap: var(--spacingVerticalS);
        max-width: 80ch;
      }
      .text-default-example__divider {
        margin: var(--spacingVerticalL) 0;
      }
    `;
    return (<>
        <style>{styles}</style>
        <div className="text-default-example">
          <Text as="h2" preset="heading3" foreground={1} block>
            Weekly status report{' '}
            <Text foreground={4} weight="regular">
              (00/00/0000)
            </Text>
          </Text>
          <Text as="p" preset="body" block>
            This paragraph uses the <Code>body</Code> preset with <Code>foreground=2</Code>, the
            standard combination for readable body copy.
          </Text>
          <Text preset="body" weight="bold" foreground={1} block>
            Action needed: review the deployment checklist before Friday.
          </Text>
          <Text as="p" preset="bodyS" block>
            For quicker styling, pass a <Code>TextPreset</Code> name in the <Code>preset</Code> prop
            instead of Fluent's separate size/weight components.
          </Text>
          <Text preset="bodyXS" foreground={4}>
            Posted 3 days ago · 5 min read
          </Text>
          <Divider className="text-default-example__divider"/>
          <div>
            <Text>Same</Text> <span>Same</span>
          </div>
          <Text as="p" block preset="bodyS" foreground={3}>
            The above two <Text italic>"Same"</Text> elements render text visually the same.{' '}
            <Code>Text</Code> components inherit css text properties by default (differently from
            Fluent's Text components) so they can be nested more constructively.
          </Text>
        </div>
      </>);
};

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.

### Text API

A text component that extends Fluent UI's Text with a `foreground` prop for
choosing one of the four neutral foreground emphasis levels, and a
`preset` prop for choosing one of CoreAI's named `size`/`weight` combos.
Unset typography properties inherit from the component's CSS parent.

```ts
interface TextProps {
  /**
   * Aligns text based on the parent container.
   * @default start
   */
  align?: "center" | "start" | "end" | "justify";

  as?: "b" | "em" | "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "i" | "p" | "pre" | "span" | "strong";

  /**
   * Applies a block display for the content.
   * @default false
   */
  block?: boolean;

  children?: any;

  className?: string;

  /**
   * Applies the font family to the content.
   * @default base
   */
  font?: "base" | "numeric" | "monospace";

  /**
   * Selects a neutral foreground emphasis level, mapping to the
   * `colorNeutralForeground1`–`colorNeutralForeground4` tokens. `1` is the
   * highest-emphasis (primary) color; `4` is the lowest-emphasis color.
   */
  foreground?: 1 | "disabled" | 2 | 3 | 4;

  /**
   * Applies the italic font style to the content.
   * @default false
   */
  italic?: boolean;

  /**
   * Selects one of CoreAI's named `size`/`weight` combos (`heading1`…`bodyXS`).
   * Supplies defaults for `size`/`weight` — pass either prop explicitly to override.
   */
  preset?: "body" | "heading1" | "heading2" | "heading3" | "heading4" | "heading5" | "bodyStrong" | "heading6" | "bodySStrong" | "bodyS" | "bodyXSStrong" | "bodyXS";

  ref?: Ref<HTMLElement>;

  /**
   * Applies font size and line height based on the theme typography tokens.
   * @default 300
   */
  size?: 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 | 1000;

  /**
   * Applies the strikethrough text decoration to the content.
   * @default false
   */
  strikethrough?: boolean;

  style?: CSSProperties;

  /**
   * Truncate overflowing text for block displays.
   * @default false
   */
  truncate?: boolean;

  /**
   * Applies the underline text decoration to the content.
   * @default false
   */
  underline?: boolean;

  /**
   * When `true`, transforms the text to uppercase (`text-transform: uppercase`).
   */
  uppercase?: boolean;

  /**
   * Applies font weight to the content.
   * @default regular
   */
  weight?: "bold" | "medium" | "regular" | "semibold";

  /**
   * Wraps the text content on white spaces.
   * @default true
   */
  wrap?: boolean;
}
```

### Display API

Text preset component for the Display typography variant

```ts
interface DisplayProps {
  /**
   * Aligns text based on the parent container.
   * @default start
   */
  align?: "center" | "start" | "end" | "justify";

  as?: "b" | "em" | "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "i" | "p" | "pre" | "span" | "strong";

  /**
   * Applies a block display for the content.
   * @default false
   */
  block?: boolean;

  children?: any;

  className?: string;

  /**
   * Applies the italic font style to the content.
   * @default false
   */
  italic?: boolean;

  /**
   * Applies the strikethrough text decoration to the content.
   * @default false
   */
  strikethrough?: boolean;

  style?: CSSProperties;

  /**
   * Truncate overflowing text for block displays.
   * @default false
   */
  truncate?: boolean;

  /**
   * Applies the underline text decoration to the content.
   * @default false
   */
  underline?: boolean;

  /**
   * Wraps the text content on white spaces.
   * @default true
   */
  wrap?: boolean;
}
```

## 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.

## Alignment

Source: Fluent, adapted for CoreAI.

[Download source](/coreai-design-system/source/examples/components-text--alignment.tsx)

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

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

const useStyles = makeStyles({
    container: {
        gap: '16px',
        display: 'flex',
        flexDirection: 'column',
        alignItems: 'stretch',
    },
});

export const Alignment = (): JSXElement => {
    const styles = useStyles();
    return (<div className={styles.container}>
      <Text align="start">Aligned to start</Text>
      <Text align="center">Aligned to center</Text>
      <Text align="end">Aligned to end</Text>
      <Text align="justify">
        Justified text: Lorem ipsum dolor sit amet consectetur adipisicing elit. Praesentium accusamus voluptate autem?
        Recusandae alias corporis dicta quisquam sequi molestias deleniti, libero necessitatibus, eligendi, omnis cumque
        enim asperiores quasi quidem sit. Lorem ipsum dolor sit amet, consectetur adipisicing elit. Possimus repellat
        consectetur, sed aperiam ex nulla repellendus tempora vero illo aliquam autem! Impedit ipsa praesentium vero
        veritatis unde eos, fuga magnam!
      </Text>
    </div>);
};

export default Alignment;
```

## Font

Source: Fluent, adapted for CoreAI.

[Download source](/coreai-design-system/source/examples/components-text--font.tsx)

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

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

const useStyles = makeStyles({
    container: {
        gap: '16px',
        display: 'flex',
        flexDirection: 'column',
    },
});

export const Font = (): JSXElement => {
    const styles = useStyles();
    return (<div className={styles.container}>
      <Text font="base">This is the default font</Text>
      <Text font="numeric">This is numeric font</Text>
      <Text font="monospace">This is monospace font</Text>
    </div>);
};

export default Font;
```

## Foreground

Source: CoreAI.

[Download source](/coreai-design-system/source/examples/components-text--foreground.tsx)

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

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

export const Foreground = () => {
    const styles = /* css */ `
    .text-foreground-example {
      display: flex;
      flex-direction: column;
      row-gap: var(--spacingVerticalS);
    }
  `;
    return (<>
      <style>{styles}</style>
      <div className="text-foreground-example">
        <Text foreground={1}>Foreground 1 — heading</Text>
        <Text foreground={2}>Foreground 2 — body (default)</Text>
        <Text foreground={3}>Foreground 3 — subtle</Text>
        <Text foreground={4}>Foreground 4 — muted</Text>
        <Text foreground={'disabled'}>Foreground Disabled — disabled</Text>
      </div>
    </>);
};

export default Foreground;
```

## Italic

Source: Fluent, adapted for CoreAI.

[Download source](/coreai-design-system/source/examples/components-text--italic.tsx)

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

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

export const Italic = (): JSXElement => <Text italic>Italic text</Text>;

export default Italic;
```

## Preset Compatibility

Source: CoreAI.

[Download source](/coreai-design-system/source/examples/components-text--preset-compatibility.tsx)

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

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

/** The `size`/`weight` each preset corresponds to, and the CoreAI `preset` (if any) that reproduces it. */
const presets: Array<{
    render: (label: string) => React.JSX.Element;
    name: string;
    coreAI?: string;
    coreAIPreset?: TextPreset;
    size: number;
    weight: string;
}> = [
    {
        render: (l) => <Text preset="bodyXS">{l}</Text>,
        name: 'Caption2',
        coreAI: 'Body XS',
        coreAIPreset: 'bodyXS',
        size: 100,
        weight: 'regular',
    },
    {
        render: (l) => <Text preset="bodyXSStrong">{l}</Text>,
        name: 'Caption2Strong',
        coreAI: 'Body XS Strong',
        coreAIPreset: 'bodyXSStrong',
        size: 100,
        weight: 'semibold',
    },
    {
        render: (l) => <Text preset="bodyS">{l}</Text>,
        name: 'Caption1',
        coreAI: 'Body S',
        coreAIPreset: 'bodyS',
        size: 200,
        weight: 'regular',
    },
    {
        render: (l) => <Text preset="bodySStrong">{l}</Text>,
        name: 'Caption1Strong',
        coreAI: 'Body S Strong',
        coreAIPreset: 'bodySStrong',
        size: 200,
        weight: 'semibold',
    },
    {
        render: (l) => (<Text size={200} weight="bold">
        {l}
      </Text>),
        name: 'Caption1Stronger',
        size: 200,
        weight: 'bold',
    },
    {
        render: (l) => <Text preset="body">{l}</Text>,
        name: 'Body1',
        coreAI: 'Body',
        coreAIPreset: 'body',
        size: 300,
        weight: 'regular',
    },
    {
        render: (l) => <Text preset="bodyStrong">{l}</Text>,
        name: 'Body1Strong',
        coreAI: 'Body Strong',
        coreAIPreset: 'bodyStrong',
        size: 300,
        weight: 'semibold',
    },
    {
        render: (l) => (<Text size={300} weight="bold">
        {l}
      </Text>),
        name: 'Body1Stronger',
        size: 300,
        weight: 'bold',
    },
    {
        render: (l) => (<Text size={400} weight="regular">
        {l}
      </Text>),
        name: 'Body2',
        size: 400,
        weight: 'regular',
    },
    {
        render: (l) => <Text preset="heading4">{l}</Text>,
        name: 'Subtitle2',
        coreAI: 'Heading 4',
        coreAIPreset: 'heading4',
        size: 400,
        weight: 'semibold',
    },
    {
        render: (l) => (<Text size={400} weight="bold">
        {l}
      </Text>),
        name: 'Subtitle2Stronger',
        size: 400,
        weight: 'bold',
    },
    {
        render: (l) => <Text preset="heading3">{l}</Text>,
        name: 'Subtitle1',
        coreAI: 'Heading 3',
        coreAIPreset: 'heading3',
        size: 500,
        weight: 'semibold',
    },
    {
        render: (l) => (<Text size={600} weight="semibold">
        {l}
      </Text>),
        name: 'Title3',
        size: 600,
        weight: 'semibold',
    },
    {
        render: (l) => <Text preset="heading2">{l}</Text>,
        name: 'Title2',
        coreAI: 'Heading 2',
        coreAIPreset: 'heading2',
        size: 700,
        weight: 'semibold',
    },
    {
        render: (l) => (<Text size={800} weight="semibold">
        {l}
      </Text>),
        name: 'Title1',
        size: 800,
        weight: 'semibold',
    },
    {
        render: (l) => <Text preset="heading1">{l}</Text>,
        name: 'LargeTitle',
        coreAI: 'Heading 1',
        coreAIPreset: 'heading1',
        size: 900,
        weight: 'semibold',
    },
    {
        render: (l) => (<Text size={1000} weight="semibold">
        {l}
      </Text>),
        name: 'Display',
        size: 1000,
        weight: 'semibold',
    },
];

export const PresetCompatibility = () => {
    // Group presets by size, then list largest size first.
    const groups = Array.from(presets.reduce((map, preset) => {
        const group = map.get(preset.size) ?? [];
        group.push(preset);
        map.set(preset.size, group);
        return map;
    }, new Map<number, typeof presets>())).sort(([a], [b]) => b - a);
    // Render every preset in a group with its own styling, separated by a '/'.
    const renderGroup = (group: typeof presets) => (<div className="text-preset-compatibility-example__cell text-preset-compatibility-example__cell--preset">
      {group.map((preset, index) => (<React.Fragment key={preset.name}>
          {index > 0 && (<Text foreground={4} size={200}>
              /
            </Text>)}
          {preset.render(preset.name)}
        </React.Fragment>))}
    </div>);
    // Render the same group with the CoreAI `Text` component's `preset` prop,
    // separated by a '/'.
    const renderCoreAIGroup = (group: typeof presets) => (<div className="text-preset-compatibility-example__cell">
      {group.map((preset, index) => (<React.Fragment key={preset.name}>
          {index > 0 && (<Text foreground={4} size={200}>
              /
            </Text>)}
          <Text preset={preset.coreAIPreset} foreground={!preset.coreAIPreset ? 'disabled' : preset.weight !== 'regular' ? 1 : undefined}>
            {preset.coreAI || '---'}
          </Text>
        </React.Fragment>))}
    </div>);
    const styles = /* css */ `
    .text-preset-compatibility-example {
      display: grid;
      grid-template-columns: max-content max-content max-content;
      align-items: baseline;
      column-gap: var(--spacingHorizontalXXL);
      row-gap: var(--spacingVerticalM);
    }

    .text-preset-compatibility-example__cell {
      display: flex;
      flex-wrap: wrap;
      align-items: baseline;
      column-gap: var(--spacingHorizontalS);
    }

    .text-preset-compatibility-example__cell--preset {
      color: var(--colorNeutralForegroundDisabled);
    }
  `;
    return (<>
      <style>{styles}</style>
      <div className="text-preset-compatibility-example">
        <Text foreground={4} size={100} uppercase weight="bold">
          CoreAI
        </Text>
        <Text foreground={4} size={100} uppercase weight="bold">
          preset
        </Text>
        <Text foreground={4} size={100} uppercase weight="bold">
          size / weight
        </Text>
        {groups.map(([size, group]) => (<React.Fragment key={size}>
            {renderCoreAIGroup(group)}
            {renderGroup(group)}
            <Text foreground={3} size={200}>
              {size} / {group.map((preset) => preset.weight).join(' / ')}
            </Text>
          </React.Fragment>))}
      </div>
    </>);
};

export default PresetCompatibility;
```

## Presets

Source: CoreAI.

`preset` selects one of CoreAI's named `size`/`weight` combinations instead
of picking `size`/`weight` (or a separate Fluent typography component)
directly — use the name that matches the content's semantic role (a
`heading*` for titles, `body`/`bodyS`/`bodyXS` for copy at decreasing
emphasis).

[Download source](/coreai-design-system/source/examples/components-text--presets.tsx)

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

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

export const Presets = () => {
    /** Every CoreAI `TextPreset`, ordered largest to smallest, alongside the
     * `size`/`weight` pair it resolves to. Aliases that share the same
     * `size`/`weight` (`heading5`/`bodyStrong`, `heading6`/`bodySStrong`) are
     * listed on one row. */
    const textPresets: Array<{
        preset: TextPreset;
        label: string;
        size: number;
        weight: string;
    }> = [
        { preset: 'heading1', label: 'heading1', size: 900, weight: 'semibold' },
        { preset: 'heading2', label: 'heading2', size: 700, weight: 'semibold' },
        { preset: 'heading3', label: 'heading3', size: 500, weight: 'semibold' },
        { preset: 'heading4', label: 'heading4', size: 400, weight: 'semibold' },
        {
            preset: 'heading5',
            label: 'heading5 / bodyStrong',
            size: 300,
            weight: 'semibold',
        },
        { preset: 'body', label: 'body', size: 300, weight: 'regular' },
        {
            preset: 'heading6',
            label: 'heading6 / bodySStrong',
            size: 200,
            weight: 'semibold',
        },
        { preset: 'bodyS', label: 'bodyS', size: 200, weight: 'regular' },
        {
            preset: 'bodyXSStrong',
            label: 'bodyXSStrong',
            size: 100,
            weight: 'semibold',
        },
        { preset: 'bodyXS', label: 'bodyXS', size: 100, weight: 'regular' },
    ];
    const styles = /* css */ `
      .text-presets-example {
        display: grid;
        grid-template-columns: max-content 1fr;
        column-gap: var(--spacingHorizontalXXL);
        row-gap: var(--spacingVerticalM);
        align-items: baseline;
      }
    `;
    return (<>
        <style>{styles}</style>
        <div className="text-presets-example">
          {textPresets.map(({ preset, label, size, weight }) => (<React.Fragment key={preset}>
              <Text preset={preset} foreground={weight === 'semibold' ? 1 : 2} block>
                {label}
              </Text>
              <Text foreground={4} size={200}>
                {size} / {weight}
              </Text>
            </React.Fragment>))}
        </div>
      </>);
};

export default Presets;
```

## Size

Source: Fluent, adapted for CoreAI.

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

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

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

const useStyles = makeStyles({
    container: {
        gap: '16px',
        display: 'flex',
        flexDirection: 'column',
        alignItems: 'baseline',
    },
});

export const Size = (): JSXElement => {
    const styles = useStyles();
    return (<div className={styles.container}>
      <Text size={100}>100</Text>
      <Text size={200}>200</Text>
      <Text size={300}>300</Text>
      <Text size={400}>400</Text>
      <Text size={500}>500</Text>
      <Text size={600}>600</Text>
      <Text size={700}>700</Text>
      <Text size={800}>800</Text>
      <Text size={900}>900</Text>
      <Text size={1000}>1000</Text>
    </div>);
};

export default Size;
```

## Strike Through

Source: Fluent, adapted for CoreAI.

[Download source](/coreai-design-system/source/examples/components-text--strike-through.tsx)

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

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

export const StrikeThrough = (): JSXElement => <Text strikethrough>Strikethrough text</Text>;

export default StrikeThrough;
```

## Truncate

Source: Fluent, adapted for CoreAI.

[Download source](/coreai-design-system/source/examples/components-text--truncate.tsx)

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

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

const useStyles = makeStyles({
    text: {
        overflow: 'hidden',
        width: '240px',
        display: 'block',
    },
});

export const Truncate = (): JSXElement => {
    const styles = useStyles();
    return (<Text truncate wrap={false} className={styles.text}>
      Lorem ipsum dolor sit, amet consectetur adipisicing elit. Facere aliquam nisi numquam, fugit recusandae eligendi
      aspernatur odio minus? Incidunt maxime ipsam dolorem quia quas aliquam, quasi consequatur! Ea, minus eaque.
    </Text>);
};

export default Truncate;
```

## Underline

Source: Fluent, adapted for CoreAI.

[Download source](/coreai-design-system/source/examples/components-text--underline.tsx)

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

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

export const Underline = (): JSXElement => <Text underline>Underlined text</Text>;

export default Underline;
```

## Weight

Source: Fluent, adapted for CoreAI.

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

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

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

const useStyles = makeStyles({
    container: {
        gap: '16px',
        display: 'flex',
        flexDirection: 'column',
    },
});

export const Weight = (): JSXElement => {
    const styles = useStyles();
    return (<div className={styles.container}>
      <Text weight="regular">Regular weight</Text>
      <Text weight="medium">Medium weight</Text>
      <Text weight="semibold">Semibold weight</Text>
      <Text weight="bold">Bold weight</Text>
    </div>);
};

export default Weight;
```