A styled anchor with typography variants, colors, and weights.
import { Link } from '@backstage/ui';
<Link href="/">Sign up for Backstage</Link>| Prop | Type | Default | Description |
|---|---|---|---|
href | string | - | URL the link navigates to. Supports internal and external URLs. |
target | _self_blank_parent_top | - | Where to open the link. Use _blank for external links that open in new tabs. |
title | string | - | Tooltip text shown on hover. Useful for accessibility. |
variant | title-largetitle-mediumtitle-smalltitle-x-smallbody-largebody-mediumbody-smallbody-x-small | body-medium | Typography style. Title variants for headings, body for paragraph text. |
weight | regularbold | regular | Font weight. Use bold for emphasis. |
color | primarysecondarydangerwarningsuccessinfo | primary | Text color. Status colors (danger, warning, success) for contextual links. |
truncate | boolean | false | Truncates text with ellipsis when it overflows its container. |
noTrack | boolean | - | Suppresses the automatic analytics click event, e.g. if you already have custom tracking. |
standalone | boolean | false | Removes underline by default. Underline appears on hover. |
children | ReactNode | - | |
className | string | - | Additional CSS class name for custom styling. |
style | CSSProperties | - | Inline CSS styles object. |
Inherits all React Aria Link props.
Use target="_blank" to open links in a new tab.
<Link href="#" target="_blank">
Sign up for Backstage
</Link>Status colors for contextual links.
<Flex gap="4">
<Link href="#" weight="regular">Regular</Link>
<Link href="#" weight="bold">Bold</Link>
</Flex>Use standalone to remove the underline by default. The underline will appear on hover.
<Flex gap="4">
<Link href="#">Default link</Link>
<Link href="#" standalone>Standalone link</Link>
</Flex>Our theming system is based on a mix between CSS classes, CSS variables and data attributes. If you want to customise this component, you can use one of these class names below.
bui-LinkBreaking Updated BUI links to use the hosting application's client-side router, including relative destinations and the application's configured router base path, while preserving native browser navigation where required.
Anchor-based components no longer accept the React Aria render prop. BUI now owns the underlying anchor so routing behavior remains consistent across application and plugin package versions.
ListRow, Tag, and table Row now retain client-side navigation when application and plugin packages load separate React Aria copies. Their existing modifier-key, target, download, and link-metadata behavior is unchanged. #35299
Migration Guide:
Remove render props from ButtonLink, ComboboxItem, Link, MenuItem, MenuListBoxItem, SearchAutocompleteItem, SelectItem, and Tab. BUI now selects and renders the appropriate anchor or router link automatically.
http://, https://, //, mailto:, tel:) are now passed through unchanged. Internal href values are resolved against the current basename exactly once, which also fixes a latent issue where internal link clicks under a non-root base path could navigate to a URL with the basename prefix doubled. #34004href resolution for BUI link components. Relative paths like ../other are now correctly turned into absolute paths before reaching the React Aria layer, ensuring client-side navigation goes to the right place. #33597Breaking Centralized client-side routing in BUIProvider. Components like Link, ButtonLink, Tabs, Menu, TagGroup, and Table now require a BUIProvider rendered inside a React Router context for client-side navigation to work. #33267
Migration Guide:
This change requires updating @backstage/plugin-app and @backstage/core-app-api alongside @backstage/ui. If you only upgrade @backstage/ui, BUI components will fall back to full-page navigation.
If you cannot upgrade all packages together, or if you have a custom app shell, add a BUIProvider inside your Router:
+ import { BUIProvider } from '@backstage/ui';
<BrowserRouter>
+ <BUIProvider>
<AppContent />
+ </BUIProvider>
</BrowserRouter>
Added analytics capabilities to the component library. Components with navigation behavior (Link, ButtonLink, Tab, MenuItem, Tag, Row) now fire analytics events on click when a BUIProvider is present.
New exports: BUIProvider, useAnalytics, getNodeText, and associated types (AnalyticsTracker, UseAnalyticsFn, BUIProviderProps, AnalyticsEventAttributes).
Components with analytics support now accept a noTrack prop to suppress event firing. #33150
Migrated all components from useStyles to useDefinition hook. Exported OwnProps types for each component, enabling better type composition for consumers. #33050
Fixed Link variant default from 'body' to 'body-medium' to match actual CSS selectors. The previous default did not correspond to a valid variant value. #33050
Breaking Removed link and tint color tokens, added new status foreground tokens, and improved Link component styling
The following color tokens have been removed:
--bui-fg-link (and all related tokens: -hover, -pressed, -disabled)--bui-fg-tint (and all related tokens: -hover, -pressed, -disabled)--bui-bg-tint (and all related tokens: -hover, -pressed, -disabled)--bui-border-tint (and all related tokens)New Status Tokens:
Added dedicated tokens for status colors that distinguish between usage on status backgrounds vs. standalone usage:
--bui-fg-danger-on-bg / --bui-fg-danger--bui-fg-warning-on-bg / --bui-fg-warning--bui-fg-success-on-bg / --bui-fg-success--bui-fg-info-on-bg / --bui-fg-infoThe -on-bg variants are designed for text on colored backgrounds, while the base variants are for standalone status indicators with improved visibility and contrast. #32608
Migration Guide:
For link colors, migrate to one of the following alternatives:
.custom-link {
- color: var(--bui-fg-link);
+ color: var(--bui-fg-info); /* For informational links */
+ /* or */
+ color: var(--bui-fg-primary); /* For standard text links */
}
For tint colors (backgrounds, foregrounds, borders), migrate to appropriate status or neutral colors:
.info-section {
- background: var(--bui-bg-tint);
+ background: var(--bui-bg-info); /* For informational sections */
+ /* or */
+ background: var(--bui-bg-neutral-1); /* For neutral emphasis */
}
If you're using status foreground colors on colored backgrounds, update to the new -on-bg tokens:
.error-badge {
- color: var(--bui-fg-danger);
+ color: var(--bui-fg-danger-on-bg);
background: var(--bui-bg-danger);
}