Link

Renders a hyperlink or button-like control with context colors, an icon-aligned layout, and a stretched click target.

Examples

<Link> renders a native <a> by default, picking up Chassis's default link color and interactive underline states.

import { Link } from '@chassis-ui/react'

export const Example = () => {
  return <Link href="#">Default link</Link>
}

Colors

Set color to one of Chassis's context colors to change a link's color, including its :hover/:focus/:active/:visited states.

import { Link } from '@chassis-ui/react'
import { COLORS } from '../../utils'

export const Example = () => {
  return (
    <>
      {COLORS.map((color) => (
        <p key={color}>
          <Link href="#" color={color}>
            {color} link
          </Link>
        </p>
      ))}
    </>
  )
}

Color alone doesn't convey meaning to assistive technology. Pair a context color with visible text describing the destination, or add hidden text via the .visually-hidden class when the color itself carries information.

Reset color

Set reset to remove the link's color override, so it inherits color from its nearest ancestor instead — useful for a link embedded in already-colored text.

Secondary body text with a reset link.

Secondary body text with a normal link.

import { Link } from '@chassis-ui/react'

export const Example = () => {
  return (
    <>
      <p className="fg-subtle">
        Secondary body text with a{' '}
        <Link href="#" reset>
          reset link
        </Link>
        .
      </p>
      <p className="fg-subtle">
        Secondary body text with a <Link href="#">normal link</Link>.
      </p>
    </>
  )
}

Icon

Set iconLink to align an icon with the link text using flexbox, with a gap between them and an offset underline. Pass the icon as children alongside the text — before it for a leading icon, after it for a trailing one.

Icon link

import { Icon, Link } from '@chassis-ui/react'

export const Example = () => {
  return (
    <Link href="#" iconLink>
      <Icon name="info-circle-solid" aria-hidden="true" />
      Icon link
    </Link>
  )
}

Decorative icons need aria-hidden="true". An icon that conveys meaning on its own needs role="img" and an aria-label instead.

Stretched

Set stretched to expand a link's click target to fill its containing block — the nearest ancestor with a position other than static. Useful for making an entire card or list row clickable through a single link.

Card title

Some placeholder content the stretched link expands to cover, edge to edge.

Go somewhere

import { Link } from '@chassis-ui/react'

export const Example = () => {
  return (
    <div className="d-flex position-relative">
      <div>
        <h4 className="mt-0">Card title</h4>
        <p>Some placeholder content the stretched link expands to cover, edge to edge.</p>
        <Link href="#" stretched>
          Go somewhere
        </Link>
      </div>
    </div>
  )
}

Root element

Set component to render <Link> as a <button> instead of an anchor, for an action that doesn't navigate but should still look like a link (see Icon and the other style props above). href implies the default <a>.

Anchor

import { Link } from '@chassis-ui/react'

export const Example = () => {
  return (
    <>
      <Link href="#">Anchor</Link>
      <Link component="button" type="button">
        Button
      </Link>
    </>
  )
}

Active state

Set active to mark a link as the current page or selection. It sets aria-current="page" so assistive technology recognizes it as the current item, alongside an .active class for styling.

Current page

import { Link } from '@chassis-ui/react'

export const Example = () => {
  return (
    <Link href="#" active>
      Current page
    </Link>
  )
}

Disabled state

Set disabled to make a link non-interactive. <a> has no disabled attribute, so a disabled anchor sets aria-disabled="true" and tabindex="-1" instead, and blocks its own click handler and navigation.

Disabled link

import { Link } from '@chassis-ui/react'

export const Example = () => {
  return (
    <Link href="#" disabled>
      Disabled link
    </Link>
  )
}

Rendered as component="button", disabled uses the real disabled attribute, which blocks keyboard and pointer interaction on its own.

import { Link } from '@chassis-ui/react'

export const Example = () => {
  return (
    <Link component="button" type="button" disabled>
      Disabled button
    </Link>
  )
}

Scope

No automatic keyboard activation on a custom component. Unlike Button, Link doesn't synthesize role="button", focus handling, or Enter/Space activation for a component other than "a" or "button" — pick Link for content that's already one of those two, or Button for a control that needs another element to behave like one.

API

Link

Prop	Type	Default
`active?`	`boolean`	—
Toggle the active state for the component.
`asChild?`	`boolean`	—
Render the single child element in place of this component's own element, with this component's classes, props and ref merged onto it: `<Button asChild><Link href="/login">Log in</Link></Button>`. The alternative to `component` for React Server Components — an element can be passed from the server to this package's client components, a component reference (`component={Link}`) can't.
`className?`	`string`	—
A string of all className you want applied to the component.
`color?`	`ContextColor`	—
Sets the link color to one of Chassis context colors, including its interactive (`:hover`/`:focus`/`:active`/`:visited`) states.
`component?`	`ElementType`	—
Component used for the root node. Either a string to use a HTML element or a component.
`disabled?`	`boolean`	—
Toggle the disabled state for the component.
`href?`	`string`	—
The href attribute specifies the URL of the page the link goes to. Reaches an `<a>` or a component reference (a router link); dropped, with a warning in development, when `component` is another element. Declared explicitly here — rather than left to flow through generically from whatever `C` is — so consumers that wrap `Link` (`MenuItem`, `ListItem`, `NavLink`) can read it with a concrete type regardless of `component`.
`iconLink?`	`boolean`	—
Aligns a leading or trailing icon with the link text using flexbox, with a gap between them and an offset underline. Icons need to be passed as `children` alongside the text. Named `iconLink` rather than `icon` to avoid colliding with components (e.g. `MenuItem`) that already have their own, differently-typed `icon` prop for the icon content itself.
`onClick?`	`MouseEventHandler<HTMLElement>`	—
Fires on click.
`ref?`	`any`	—

`reset?`	`boolean`	—
Removes the foreground color override, so the link inherits its color from the nearest ancestor instead of the default link color.
`stretched?`	`boolean`	—
Expands the link's click target to fill its positioned ancestor (the nearest ancestor with a `position` other than `static`).
`type?`	`"button" \| "reset" \| "submit"`	—
Specifies the type of button. Only applies when `component="button"`. Different browsers may use different default types for the `<button>` element, so always specify it explicitly.