# @atlaskit/teams-app-internal-navigation

> Headless navigation utilities for consistent internal link behaviour across the Teams app.

Latest version **3.1.0** (published 2026-10-13) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @atlaskit/teams-app-internal-navigation
pnpm add @atlaskit/teams-app-internal-navigation
yarn add @atlaskit/teams-app-internal-navigation
bun add @atlaskit/teams-app-internal-navigation
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 3.1.0 |
| Published | 2026-10-13 |
| First published | 2026-03-17 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 7 |
| Unpacked size | 151 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Atlassian Pty Ltd |
| Maintainers | atlassianartifactteam |

## Links

- npm: https://www.npmjs.com/package/@atlaskit/teams-app-internal-navigation
- Repository: https://bitbucket.org/atlassian/atlassian-frontend-monorepo
- Homepage: https://bitbucket.org/atlassian/atlassian-frontend-monorepo#readme
- Issues: https://bitbucket.org/atlassian/atlassian-frontend-monorepo/issues
- npm.io page: https://npm.io/package/@atlaskit/teams-app-internal-navigation

## Dependencies (7)

- [@atlaskit/link](https://npm.io/package/@atlaskit/link.md) ^5.1.0
- [@atlaskit/menu](https://npm.io/package/@atlaskit/menu.md) ^11.0.0
- [@babel/runtime](https://npm.io/package/@babel/runtime.md) ^7.0.0
- [@atlaskit/button](https://npm.io/package/@atlaskit/button.md) ^25.4.0
- [@atlaskit/primitives](https://npm.io/package/@atlaskit/primitives.md) ^22.5.0
- [@atlaskit/react-compiler-gating](https://npm.io/package/@atlaskit/react-compiler-gating.md) ^0.2.0
- [@atlaskit/platform-feature-flags](https://npm.io/package/@atlaskit/platform-feature-flags.md) ^2.2.0

## Recent versions

- 3.1.0 (latest) — 2026-10-13
- 3.0.1 — 2026-10-08
- 3.0.0 — 2026-09-24
- 2.3.1 — 2026-09-17
- 2.3.0 — 2026-08-19
- 2.2.1 — 2026-08-05
- 2.2.0 — 2026-08-04
- 2.1.4 — 2026-07-30
- 2.1.3 — 2026-07-29
- 2.1.2 — 2026-07-17
- 2.1.1 — 2026-07-16
- 2.1.0 — 2026-06-26
- 2.0.1 — 2026-06-23
- 2.0.0 — 2026-06-16
- 1.9.0 — 2026-05-01
- … 20 more at https://npm.io/package/@atlaskit/teams-app-internal-navigation/versions

## README

# @atlaskit/teams-app-internal-navigation

Headless navigation utilities and thin UI wrappers for the Teams app and People & Teams platform
packages. Ensures internal and external links behave consistently across the Teams app and embedded
People/Teams surfaces.

## Usage

### Basic Usage

Wrap your app with `TeamsNavigationProvider` and use the link components directly:

```tsx
import { TeamsNavigationProvider } from '@atlaskit/teams-app-internal-navigation/teams-navigation-provider';
import { TeamsAnchor } from '@atlaskit/teams-app-internal-navigation/teams-anchor';

function MyComponent() {
	return (
		<TeamsNavigationProvider value={{ navigate: pushRoute }}>
			<TeamsAnchor href="/teams/my-team" intent="navigation">
				My team
			</TeamsAnchor>
		</TeamsNavigationProvider>
	);
}
```

A complete example with `TeamsLink`, `TeamsLinkItem` and `TeamsLinkButton` is in
[`examples/basic.tsx`](./examples/basic.tsx).

### Headless API

Use `getNavigationProps` when you need to compose navigation behaviour onto custom markup or
non-ADS components:

```ts
import { getNavigationProps } from '@atlaskit/teams-app-internal-navigation/get-navigation-props';
```

It returns `href`, `target`, `rel` and a composed `onClick` from an `href`, intent,
`NavigationContext` and optional `onClick`.

## Features

### Navigation Intents

Each link declares an **intent** that controls how the browser or app handles the navigation:

- **`navigation`**: Moving within or between Atlassian apps
- **`reference`**: Documentation, support, or reference-style URLs
- **`action`**: Inline flows that may open a preview panel when the required props are set
- **`external`**: Third-party or explicitly external destinations
- **`unknown`**: Intent inferred automatically from the URL via `classifyNavigationIntent`

Automatic classification considers relative vs absolute URLs, non-HTTP schemes (`mailto:`, `tel:`,
etc.) and Atlassian-managed hosts (including FedRAMP and isolated cloud handling).

### Navigation Context

`TeamsAnchor`, `TeamsLink`, `TeamsLinkButton` and `TeamsLinkItem` all read from
`NavigationContext` via React context. The provider accepts:

- **`navigate(url)`**: When set, used for SPA-style navigation. When omitted, the browser handles
  navigation (e.g. full page load).
- **`openPreviewPanel(props)`**: Optional callback. For `action` intent, left-click can open a
  preview panel instead of navigating.
- **`forceExternalIntent`**: When `true`, links behave as external opens (e.g. new tab) even if
  the URL would otherwise be treated as in-app navigation — useful inside a preview panel.

## Package Exports

The main entry `@atlaskit/teams-app-internal-navigation` exports `TeamsAnchor`,
`TeamsNavigationProvider` and `useTeamsNavigationContext`.

| Subpath | Exports |
| --- | --- |
| `/teams-anchor` | `TeamsAnchor` (wraps ADS `Anchor`) |
| `/teams-link` | `TeamsLink` (wraps ADS `Link`) |
| `/teams-link-button` | `TeamsLinkButton` (wraps ADS `LinkButton`) |
| `/teams-link-item` | `TeamsLinkItem` (wraps ADS `LinkItem`) |
| `/teams-navigation-provider` | `TeamsNavigationProvider`, `useTeamsNavigationContext` |
| `/get-navigation-props` | `getNavigationProps`, `NavigationContext`, `NavigationIntent`, `NavigationIntentProps` |

---
_Source: https://npm.io/package/@atlaskit/teams-app-internal-navigation · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
