Button Link

ButtonLink is a native link presented with the visual emphasis of a button. It preserves link behavior while drawing attention to an important destination, such as a sign-up flow, documentation page, download, or next step.

Basic usage

Provide an href and a visible label that identifies the destination.

---
import { ButtonLink } from "@ulubit/ui";
---

<ButtonLink href="/getting-started">
  Get started
</ButtonLink>

Use Button instead when activating the control should perform an action without navigating, such as saving changes or opening a dialog.

Variants

Variants communicate a link’s relative importance within the surrounding interface.

Primary

Use the primary variant for the main navigation action in a section or page.

For example, use it for the main Get started link on a product introduction page.

<ButtonLink href="/getting-started">
  Get started
</ButtonLink>

Avoid presenting several primary button links together when one destination should have clear priority.

Secondary

Use the secondary variant for an alternative destination that should receive less emphasis than the primary link.

For example, pair View documentation with a primary Get started link.

<ButtonLink href="/documentation" variant="secondary">
  View documentation
</ButtonLink>

Tertiary

Use the tertiary variant for lower-emphasis navigation that should remain available without competing with the main destinations.

For example, use it to link from a component overview to its API reference.

<ButtonLink href="/components/button#api" variant="tertiary">
  View API reference
</ButtonLink>

The danger variant is intentionally unavailable. Destructive operations must use a native Button at the point where the action occurs.

The primary, secondary, and tertiary variants use the same color tokens as Button. See Button color tokens for the complete reference.

Sizes

Sizes control the link’s dimensions, not its importance. Use variant to communicate navigation hierarchy.

Small

Use the small size in compact interfaces, such as cards, table rows, or toolbars.

<ButtonLink href="/projects/ulubit" size="sm">
  View project
</ButtonLink>

Do not use small button links as the default for ordinary page navigation.

Medium

Medium is the default size and should be used in most interfaces.

<ButtonLink href="/getting-started">
  Get started
</ButtonLink>

<!-- The explicit form is equivalent: -->

<ButtonLink href="/getting-started" size="md">
  Get started
</ButtonLink>

Large

Use the large size for a prominent destination in a spacious layout, such as the main call to action on a landing page.

<ButtonLink href="/services" size="lg">
  Explore services
</ButtonLink>

Icons

Button links can include a decorative icon before or after the visible label.

Leading icon

Use the start slot for an icon that appears before the label.

<ButtonLink href="/downloads/guide.pdf" download>
  <DownloadIcon slot="start" />
  Download guide
</ButtonLink>

Trailing icon

Use the end slot for an icon that appears after the label.

<ButtonLink href="/components/button" variant="secondary">
  View Button
  <ArrowRightIcon slot="end" />
</ButtonLink>

Icons supplement the visible label and are hidden from assistive technologies by the component. The text must identify the destination without relying on the icon.

Do not use ButtonLink without a visible label. Icon-only navigation requires a separate accessibility and sizing contract.

Full width

Button links are sized to their content by default.

Use fullWidth when the link should fill the available inline space of its container, such as in a narrow call-to-action panel or stacked mobile layout.

<div class="call-to-action">
  <ButtonLink href="/getting-started" fullWidth>
    Get started
  </ButtonLink>
</div>

The parent layout remains responsible for constraining the available width.

Do not use full width as a substitute for selecting the correct variant.

Disabled state

ButtonLink does not support a disabled state because native links do not have a disabled attribute.

When navigation is unavailable, do not render an inactive anchor. Explain what the user must do before the destination becomes available.

{canContinue ? (
  <ButtonLink href="/next-step">
    Continue
  </ButtonLink>
) : (
  <p>Complete the required fields to continue.</p>
)}

Content guidelines

Use a short label that describes the destination or what the user will find there.

Prefer:

• Get started
• View documentation
• Browse components
• Download guide

Avoid vague labels such as:

• Click here
• Go
• More
• Learn more

A contextual label such as Learn more about accessibility is acceptable because it identifies the destination.

Use sentence case unless a proper name requires different capitalization.

Accessibility

ButtonLink renders a native <a> element and retains its built-in navigation, keyboard, and browser behavior.

All variants provide default, hover, active, visited, and focus-visible visual states.

The visible label should identify the destination. Do not rely on surrounding content alone to explain an ambiguous link.

Decorative icons are hidden from assistive technologies because the visible label already provides the accessible name.

API

The component accepts all valid native <a> attributes.

Native attributes such as target, rel, download, hreflang, aria-*, and data-* are forwarded to the underlying <a> element.