Link & href

Navegação declarativa e links amigáveis para prefetch. Link mapeia para navegação semelhante a âncoras na web e alvos de toque acessíveis em nativo - router lida com fluxos imperativos após efeitos colaterais.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

import { Link, router, type Href } from "expo-router";
import { Pressable, Text, View } from "react-native";
 
// href de string - apenas caminhos estáticos
<Link href="/settings">Configurações</Link>
 
// href de objeto - segmentos dinâmicos (preferido)
<Link href={{ pathname: "/orders/[id]", params: { id: "42" } }}>
  Pedido 42
</Link>
 
// Imperativo após mutação
router.replace("/(tabs)");
 
// Prefetch ao pairar/focar (web) ou manualmente
<Link href="/orders" prefetch />

// src/navigation/routes.ts
import type { Href } from "expo-router";
 
export const routes = {
  home: "/" as Href,
  settings: "/settings" as Href,
  orderDetail: (id: string): Href => ({
    pathname: "/orders/[id]",
    params: { id },
  }),
};

Quando usar isso:

• Link - linhas de lista, links de texto inline, navegação adjacente a abas, âncoras web amigáveis para SEO
• router.push - navegar após envio de formulário, digitalizar QR ou callback de timer
• router.replace - pós-login, pós-logout, conclusão de onboarding
• prefetch - telas com bundles pesados ou waterfalls de dados lentos

Exemplo de Trabalho

Tela de lista com Link, Pressable personalizado via asChild, navegação imperativa e construtores de href centralizados.

// src/navigation/routes.ts
import type { Href } from "expo-router";
 
export function orderDetailHref(id: string): Href {
  return { pathname: "/orders/[id]", params: { id } };
}
 
export function settingsHref(): Href {
  return "/settings";
}

// features/orders/ui/OrdersListScreen.tsx
import { Link, router } from "expo-router";
import { Pressable, Text, View } from "react-native";
import { orderDetailHref } from "@/navigation/routes";
 
const ORDERS = [
  { id: "101", label: "Envio de widget" },
  { id: "102", label: "Peça de reposição" },
];
 
export function OrdersListScreen() {
  return (
    <View style={{ flex: 1, padding: 16, gap: 12 }}>
      {ORDERS.map((order) => (
        <Link key={order.id} href={orderDetailHref(order.id)} prefetch asChild>
          <Pressable style={{ padding: 12, backgroundColor: "#f1f5f9", borderRadius: 8 }}>
            <Text>{order.label}</Text>
          </Pressable>
        </Link>
      ))}
 
      <Link href="/settings">Configurações da conta</Link>
 
      <Pressable
        onPress={() => router.push(orderDetailHref("draft"))}
        accessibilityRole="button"
      >
        <Text>Criar rascunho (imperativo)</Text>
      </Pressable>
    </View>
  );
}

// Após o envio bem-sucedido do formulário - replace evita a pilha de volta para o formulário
import { router } from "expo-router";
 
async function onSubmit() {
  await saveProfile();
  router.replace("/(tabs)/profile");
}

// Fechar fluxo modal
import { router } from "expo-router";
 
function closeModal() {
  if (router.canGoBack()) {
    router.back();
  } else {
    router.replace("/");
  }
}

Mergulho Profundo

Formas de href

// Navegação relativa dentro de app/orders/
<Link href="./[id]" params={{ id: "5" }}>Relativo</Link>

• Params são sempre strings quando analisados de URLs - converta números na tela
• Params de consulta - href="/search?q=shoes" ou params: { q: "shoes" } dependendo da forma da rota
• Habilite rotas tipadas para que valores pathname inválidos falhem em tempo de compilação - veja Rotas Tipadas

Link vs router

// Props de Link que importam em produção
<Link
  href="/orders"
  prefetch                    // pré-carrega o módulo da rota
  replace                     // substitui o histórico em vez de push
  push                        // força push mesmo quando replace seria o padrão
  asChild                     // mescla em Pressable filho
  disabled={!isReady}
/>

Comportamento de Prefetch

• prefetch em Link - Expo Router carrega o bundle JavaScript da rota de destino antes da navegação
• Mais impactante para abas lazy e telas pesadas com grandes árvores de dependência
• Na web, o prefetch pode acionar foco/hover dependendo da versão - verifique em seu SDK de destino
• Não pré-carregue rotas protegidas por autenticação antes que a sessão seja conhecida - largura de banda desperdiçada e flicker

Padrão asChild

<Link href="/settings" asChild>
  <Pressable style={styles.row}>
    <Text>Configurações</Text>
  </Pressable>
</Link>

• O filho deve encaminhar props (onPress, href na web) - use Pressable ou componentes personalizados que espalham props
• Evite aninhar botões dentro de botões - um pressable por Link
• Defina accessibilityRole="link" na web; Pressable herda o comportamento de link de Link

Construtores de href centralizados

// packages/navigation/src/hrefs.ts (monorepo)
export const orderDetailHref = (id: string) =>
  ({ pathname: "/orders/[id]", params: { id } }) as const;

• Um módulo evita erros de digitação entre recursos
• Apps de marca branca compartilham packages/navigation quando as formas de rota correspondem
• Combine com Zod para validar params na entrada da tela - os construtores de href não validam a entrada em tempo de execução

Armadilhas

• Concatenação de strings para caminhos dinâmicos - href={'/orders/' + id} ignora rotas tipadas e quebra quando os segmentos mudam. Correção: Forma de objeto ou orderDetailHref(id).

• router.push após login - o gesto de voltar retorna ao login. Correção: router.replace.

• Link envolvendo componentes que não encaminham props - linhas personalizadas ignoram o toque. Correção: asChild + espalhar props, ou usar Pressable.

• URLs externas em router.push - podem não abrir o navegador. Correção: import { openURL } from "expo-linking" para links https://.

• Prefetching de rotas protegidas - exibe conteúdo não autorizado. Correção: Restrinja o prefetch com verificação de sessão ou pule em telas de autenticação.

• accessibilityRole ausente em Pressable imperativo - leitores de tela anunciam "botão" para navegação. Correção: accessibilityRole="link" ou prefira Link.

• Grandes cargas de payload de params em href - inchaço do estado de navegação, logs vazam dados. Correção: Passe apenas IDs; carregue corpos do store ou API.

Alternativas

FAQs

router.push({ pathname: "/search", params: { q: "shoes", sort: "price" } });

<Link href="/checkout" disabled={!cartReady} asChild>
  <Pressable disabled={!cartReady}>
    <Text>Checkout</Text>
  </Pressable>
</Link>

import * as Linking from "expo-linking";
 
await Linking.openURL("https://docs.expo.dev/router/introduction/");

Relacionados

• Rotas Tipadas - segurança Href em tempo de compilação
• Redirecionamentos e Rotas de Índice - Redirect vs router.replace
• Navegação em Pilha - comportamento da pilha de volta
• Noções Básicas do Expo Router - layout de arquivos de rota
• ../expo-rules/navigation-and-routing-rules/navigation-and-routing-rules.md - regras de Link vs imperativas
• ../architecture-design/adr-navigation-library-choice/adr-navigation-library-choice.md - justificativa de deep linking

Versões da Pilha: Esta página foi escrita para React 19.2.3, React Native 0.86.0 e Expo SDK 57 (expo ~57.0.4).