# Link

Link component does not support breaking and wrapping onto the next line. In that case, use another Link component.

## Best practices

### Do

- Use links for navigation.
- Use the default link style most of the time.
- Make link text understandable out of context.

### Don't

- Use links to trigger non-navigation actions.
- Label links with URLs or generic phrases such as “Click here.”
- Open a new tab or window without warning.

## Behavior and states

- By default, links show an underline in hover, focus, and pressed states.
- Inline link behavior also adds an underline in rest and visited states.
- Use inline behavior to maximize visual cues when a link appears next to body text.

## Default

Source: CoreAI.

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

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

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

export const Default = () => {
    return <Link href="https://www.bing.com">This is a link</Link>;
};

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.

### Link API

A link component that extends Fluent UI's Link with an `external` flag that
appends an inline external-link icon after the link text.

```ts
interface LinkProps {
  /**
   * A link can appear either with its default style or subtle.
   * If not specified, the link appears with its default styling.
   * @default 'default'
   */
  appearance?: "subtle" | "default";

  as?: "a" | "button" | "span";

  children?: any;

  className?: string;

  /**
   * Whether the link is disabled.
   * @default false
   */
  disabled?: boolean;

  /**
   * When set, allows the link to be focusable even when it has been disabled. This is used in scenarios where it is
   * important to keep a consistent tab order for screen reader and keyboard users.
   * @default false
   */
  disabledFocusable?: boolean;

  /**
   * When `true`, renders an external-link icon inline after the link text to
   * signal that the destination opens outside the current context.
   * Defaults `target` to `_blank` and `rel` to `noopener noreferrer`.
   */
  external?: boolean;

  /**
   * If true, changes styling when the link is being used alongside other text content.
   * @default false
   */
  inline?: boolean;

  ref?: Ref<HTMLSpanElement>;

  rel?: string;

  style?: CSSProperties;

  target?: HTMLAttributeAnchorTarget;
}
```

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

## Appearance

Source: Fluent, adapted for CoreAI.

[Download source](/coreai-design-system/source/examples/components-link--appearance.tsx)

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

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

export const Appearance = (): JSXElement => (<Link appearance="subtle" href="https://www.bing.com">
    Subtle link
  </Link>);

export default Appearance;
```

## As Button

Source: Fluent, adapted for CoreAI.

When the `href` property is not provided, the component is rendered as an html `<button>`

[Download source](/coreai-design-system/source/examples/components-link--as-button.tsx)

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

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

export const AsButton = (): JSXElement => <Link>Render as a button</Link>;

export default AsButton;
```

## As Span

Source: Fluent, adapted for CoreAI.

A Link can be rendered as an html `<span>`, in which case it will have `role="button"` set.
Links that render as a span wrap correctly between lines, behaving as inline elements as opposed to links rendered as buttons, which always behave as inline-block elements that do not wrap correctly.

[Download source](/coreai-design-system/source/examples/components-link--as-span.tsx)

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

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

const useDivWithWidthClassName = makeResetStyles({
    width: '200px',
});

export const AsSpan = (): JSXElement => (<div className={useDivWithWidthClassName()}>
    The following link renders as a span.{' '}
    <Link as="span" inline onClick={() => alert('Link rendered as span')}>
      Links that render as a span wrap correctly between lines when their content is very long
    </Link>
    . This is because they behave as regular inline elements.
  </div>);

export default AsSpan;
```

## Disabled

Source: Fluent, adapted for CoreAI.

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

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

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

export const Disabled = (): JSXElement => (<Link disabled href="https://www.bing.com">
    Disabled link
  </Link>);

export default Disabled;
```

## Disabled Focusable

Source: Fluent, adapted for CoreAI.

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

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

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

export const DisabledFocusable = (): JSXElement => (<Link inline disabled disabledFocusable href="https://www.bing.com">
    Disabled but still focusable
  </Link>);

export default DisabledFocusable;
```

## External

Source: CoreAI.

[Download source](/coreai-design-system/source/examples/components-link--external.tsx)

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

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

export const External = () => {
    const styles = /* css */ `
      .link-external-example {
        display: flex;
        flex-direction: column;
        align-items: flex-start;
        row-gap: var(--spacingVerticalL);
        padding: var(--spacingVerticalL);
      }

      .link-external-example__field {
        display: flex;
        flex-direction: column;
        align-items: flex-start;
        row-gap: var(--spacingVerticalXS);
      }

      .link-external-example__prop-label {
        font-family: var(--fontFamilyMonospace);
        font-size: var(--fontSizeBase200);
        color: var(--colorNeutralForeground3);
      }
    `;
    return (<>
        <style>{styles}</style>
        <div className="link-external-example">
          <div className="link-external-example__field">
            <code className="link-external-example__prop-label">external={'{false}'}</code>
            <Link href="https://example.com">Internal link</Link>
          </div>

          <div className="link-external-example__field">
            <code className="link-external-example__prop-label">external</code>
            <Link href="https://example.com" external>
              External link
            </Link>
          </div>
        </div>
      </>);
};

export default External;
```

## Inline

Source: Fluent, adapted for CoreAI.

[Download source](/coreai-design-system/source/examples/components-link--inline.tsx)

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

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

export const Inline = (): JSXElement => (<div>
    This is an{' '}
    <Link href="https://www.bing.com" inline>
      inline link
    </Link>{' '}
    used alongside other text
  </div>);

export default Inline;
```

## Resources

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