# Link
## Summary
`Link` is the navigational text action component for inline and standalone navigation affordances. It is the default choice when the interaction changes location rather than mutating state.
## Imports
```tsx
import { Link, type LinkProps } from '@vega-ui/react';
```
## Exported Types
- `LinkProps`
## Basic Usage
```tsx
import { Link, Text } from '@vega-ui/react';
export default function BasicUsage() {
return (
Exports include every invoice from the selected period. Read how we calculate{' '}
VAT for EU customers{' '}
before sharing the file with your accountant.
);
}
```
## Variants
- Inline text link versus standalone navigational action
- Default anchor rendering versus `asChild` composition
## Edge Cases
- Use real navigation targets, not button-like behavior disguised as links.
- `asChild` is useful for router integrations while preserving link styling.
- Focus and underline behavior should be checked against surrounding typography.
- If the desired presentation is a strong call-to-action surface, `Button asChild` may be clearer than a plain text link.
## Common Mistakes
- Using `Link` for actions that mutate state.
- Styling a link like a button without considering semantics.
- Using vague link text such as "Click here".
## Examples
### Basic
#### Basic: standalone link after a list
A standalone link names its destination ("View all 48 invoices") instead of "Click here". The arrow is decorative: `Icon` hides it from screen readers.
```tsx
import { Heading, Icon, Link } from '@vega-ui/react';
import { ArrowRightIcon } from '@vega-ui/icons';
import './examples.css';
const invoices = [
{ id: 'INV-2041', amount: '$1,240.00' },
{ id: 'INV-2040', amount: '$860.50' },
{ id: 'INV-2039', amount: '$2,115.00' },
];
export default function StandaloneNavigationLink() {
return (
Recent invoices
{invoices.map((invoice) => (
{invoice.id}{invoice.amount}
))}
View all 48 invoices
);
}
```
### Controlled/Stateful
#### Controlled/Stateful: router link with the current page
`Link asChild` passes its styling to a router link. The parent owns the current route and marks the active item with `aria-current='page'`; here the router is simulated with `preventDefault`.
```tsx
import { type AnchorHTMLAttributes, type MouseEvent, useState } from 'react';
import { Link } from '@vega-ui/react';
interface RouterLinkProps extends AnchorHTMLAttributes {
to: string
onNavigate(to: string): void
}
function RouterLink({ to, onNavigate, onClick, ...props }: RouterLinkProps) {
const handleClick = (event: MouseEvent) => {
onClick?.(event);
event.preventDefault();
onNavigate(to);
};
return ;
}
const pages = [
{ to: '/settings/profile', label: 'Profile' },
{ to: '/settings/team', label: 'Team' },
{ to: '/settings/billing', label: 'Billing' },
];
export default function RouterComposedLink() {
const [pathname, setPathname] = useState('/settings/profile');
return (
Current route: {pathname}
);
}
```
### Form/Integration
#### Form/Integration: forgot password link in a sign-in form
A link inside a form navigates and never submits. It sits next to the password label, after the email field in tab order, and the form reads its values with `FormData` on submit.
```tsx
import { Button, Label, Link, TextField, TextFieldInput } from '@vega-ui/react';
import { FormEvent, useState } from 'react';
export default function ForgotPasswordLink() {
const [signedIn, setSignedIn] = useState('');
const handleSubmit = (event: FormEvent) => {
event.preventDefault();
setSignedIn(String(new FormData(event.currentTarget).get('email')));
};
return (
);
}
```
### Layout/Overlay
#### Layout/Overlay: help link inside dialog copy
An inline link in the dialog description gives context without becoming one of the dialog actions. The text is linked to the dialog with `aria-describedby`.
```tsx
import type { CSSProperties } from 'react';
import {
Button,
Dialog,
DialogClose,
DialogContent,
DialogTrigger,
Heading,
Icon,
IconButton,
Link,
Text,
} from '@vega-ui/react';
import { XIcon } from '@vega-ui/icons';
export default function InlineHelpLinkInsideDialogCopy() {
return (
);
}
```
### Error
#### Error: recovery link in an error message
When a payment fails, the error message contains the way out. The message is announced with `role='alert'` and linked to the button with `aria-describedby`.
```tsx
import { Button, HelperText, Link } from '@vega-ui/react';
import { useState } from 'react';
export default function RecoveryLinkAfterAFailedFlow() {
const [declined, setDeclined] = useState(false);
return (
{declined && (
Your card ending in 4242 was declined.{' '}
Update your payment method{' '}
and try again.
)}
);
}
```
### Disabled
#### Disabled: plain text until the destination exists
Links have no disabled state, and `Link` has no disabled styles. While the report is not ready, render text that explains why, and switch to a real link once it can be followed.
```tsx
import { Button, Link } from '@vega-ui/react';
import { useState } from 'react';
export default function UnavailableLinkAsText() {
const [ready, setReady] = useState(false);
return (
{ready && Download the Q4 report}
{!ready && (
Q4 report is being generated and will be available in about 5 minutes
)}
);
}
```
### Edge
#### Edge: external link that opens a new tab
`target='_blank'` changes the context without warning, so the link says so: a decorative icon for sighted users and a `VisuallyHidden` note for screen readers. `rel='noopener noreferrer'` keeps the new page from controlling this one.
```tsx
import { Icon, Link, Text, VisuallyHidden } from '@vega-ui/react';
import { ExternalLinkIcon } from '@vega-ui/icons';
export default function ExternalLinkNewTab() {
return (
Payments are processed by{' '}
Stripe’s privacy policy
(opens in a new tab)
.
);
}
```
#### Edge: long URL in a narrow container
A URL has no spaces to break on and overflows narrow cards. `overflowWrap: 'anywhere'` lets it wrap at any character.
```tsx
import { Link, Text } from '@vega-ui/react';
const webhookUrl = 'https://hooks.example.com/services/T024BE7LD/B08S9Q2KJ7H/aD4f9kLq2ZxR7mN3pW8vY1cE';
export default function LongUrlWrapping() {
return (
Events are sent to{' '}
{webhookUrl}
);
}
```
## Anatomy
### Overview
`Link` is a single navigational text surface. Its anatomy is one anchor-like root plus inline or standalone text content, optionally rendered through `asChild`.
### Required Parts
#### `Link`
Required. Owns link styling and anchor semantics when rendered directly.
### Optional Parts
`Link` does not expose public child parts.
### Composition Order
1. `Link`
2. inline or standalone text content
### Valid Composition Patterns
```tsx
import { Link, Text } from '@vega-ui/react';
export default function BasicUsage() {
return (
Exports include every invoice from the selected period. Read how we calculate{' '}
VAT for EU customers{' '}
before sharing the file with your accountant.
);
}
```
### Invalid Composition Patterns
#### Link used for state mutation
If the interaction mutates state instead of navigating, use `Button`.
#### Vague link copy
Inline text like "Click here" weakens scanability and accessibility.