# Link

A navigation component that provides client-side routing capabilities for internal links and
external link handling.

## Import

```tsx
import { Link } from "zudoku/components";
```

## Usage

### Basic Internal Link

```tsx
<Link to="/docs/getting-started">Get Started</Link>
```

### Link with State

```tsx
<Link to="/profile" state={{ from: "header" }}>
  Profile
</Link>
```

### Replace History Entry

```tsx
<Link to="/login" replace>
  Login
</Link>
```

### External Link Behavior

```tsx
<Link to="/docs" reloadDocument>
  Full Page Reload
</Link>
```

## Examples

### Navigation Menu

```tsx
function Navigation() {
  return (
    <nav>
      <Link to="/">Home</Link>
      <Link to="/docs">Documentation</Link>
      <Link to="/api">API Reference</Link>
      <Link to="/blog">Blog</Link>
    </nav>
  );
}
```

### Breadcrumb Navigation

```tsx
function Breadcrumbs({ path }) {
  return (
    <div className="breadcrumbs">
      <Link to="/">Home</Link>
      <span>/</span>
      <Link to="/docs">Docs</Link>
      <span>/</span>
      <span>{path}</span>
    </div>
  );
}
```

### Dynamic Links

```tsx
function DocsList({ docs }) {
  return (
    <ul>
      {docs.map((doc) => (
        <li key={doc.id}>
          <Link to={`/docs/${doc.slug}`}>{doc.title}</Link>
        </li>
      ))}
    </ul>
  );
}
```

### Conditional Linking

```tsx
function ConditionalLink({ to, disabled, children }) {
  if (disabled) {
    return <span className="disabled-link">{children}</span>;
  }

  return <Link to={to}>{children}</Link>;
}
```

## Link Types

### Relative Links

```tsx
// Relative to current route
<Link to="../parent-page">Up one level</Link>

// Relative to path
<Link to="./sibling-page" relative="path">
  Sibling page
</Link>
```

### Absolute Links

```tsx
<Link to="/absolute/path">Absolute Path</Link>
```

### Query Parameters

```tsx
<Link to="/search?q=react&type=docs">Search Results</Link>
```

### Hash Links

```tsx
<Link to="/docs/api#authentication">Authentication Section</Link>
```

## Advanced Usage

### With Custom Styling

```tsx
<Link to="/important-page" className="text-blue-600 hover:text-blue-800 underline">
  Important Page
</Link>
```

### Programmatic Navigation

```tsx
import { useNavigate } from "react-router";

function MyComponent() {
  const navigate = useNavigate();

  const handleClick = () => {
    // Perform some logic
    navigate("/next-page");
  };

  return (
    <div>
      <Link to="/direct-link">Direct Link</Link>
      <button onClick={handleClick}>Programmatic Navigation</button>
    </div>
  );
}
```

### Link with Confirmation

```tsx
function DeleteLink({ itemId }) {
  const handleClick = (e) => {
    if (!confirm("Are you sure you want to delete this item?")) {
      e.preventDefault();
    }
  };

  return (
    <Link to={`/items/${itemId}/delete`} onClick={handleClick} className="text-red-600">
      Delete Item
    </Link>
  );
}
```

## Integration with Button

Use the Link component with the Button component's `asChild` prop:

```tsx
<Button asChild variant="outline">
  <Link to="/action">Perform Action</Link>
</Button>
```

## Accessibility

The Link component maintains accessibility best practices:

- Proper focus management
- Keyboard navigation support
- Screen reader compatibility
- Semantic HTML structure

```tsx
<Link to="/help" aria-label="Get help and support">
  Help
</Link>
```

## Performance

- **Client-side routing**: No full page reloads for internal navigation
- **Prefetching**: Intelligent prefetching of linked resources
- **View transitions**: Smooth transitions between pages (when supported)

## Notes

:::tip

The Link component is optimized for internal navigation and provides the best user experience for
single-page application routing.

:::

:::info

For external links, use a regular `<a>` tag instead of the Link component to ensure proper external
navigation behavior.

:::

:::caution

When using `reloadDocument`, the link will perform a full page reload, which may impact performance
and user experience.

:::