Adicionar uma tour guiada, um walkthrough ou marcadores de instruções em um aplicativo React Native parece simples até que você encontre os problemas reais: medir a posição do componente, escurecer tudo exceto ele, manter o tooltip na tela e rolar para alvos abaixo da placa. Várias bibliotecas resolvem isso. Aqui está uma comparação honesta e prática das principais opções em 2026.
Rápida resposta: react-native-copilot é a escolha padrão há muito tempo com a maior comunidade. rn-tourguide adiciona máscara SVG em cima do modelo copilot. react-native-spotlight-tour é a opção mais limpa e simples. react-native-tour-guide é a escolha se você quiser que o spotlight automaticamente corresponda à forma do seu componente, rolar automaticamente para alvos fora da placa e funcionar no Expo Go sem dependências nativas.
TL;DR
| Biblioteca | Expo Go | Dependências nativas | Ajuste automático de forma | Rolagem automática | TS | Melhor para |
|---|---|---|---|---|---|---|
| react-native-copilot | ⚠️ precisa de configuração | Algumas | Não | Parcial | Sim | A escolha padrão há muito tempo, base instalada grande |
| rn-tourguide | ⚠️ | react-native-svg | Não | Não | Sim | Fork do copilot com máscara SVG |
| react-native-spotlight-tour | ⚠️ | Algumas | Círculo/retângulo apenas | Não | Sim | Simples spotlight, boas documentações |
| react-native-tour-guide | ✅ funciona no Go | Nenhuma (svg apenas) | Sim (por canto) | Sim | Sim | Spotlights precisos, Expo Go, telas rolando |
O que procurar em uma biblioteca de tour React Native
- Precisão do spotlight — a forma da cutout corresponde à forma do seu componente (um avatar circular, um botão de pílula, um cartão com cantos de 12px), ou é sempre um retângulo/círculo que você configura manualmente?
- Rolagem — ele rola o alvo para a tela se estiver fora dela, mantendo a tooltip visível também?
- Compatibilidade com Expo — funciona no Expo Go, ou você precisa de uma build personalizada (módulos nativos)?
- Posicionamento da tooltip — ele escolhe automaticamente um lado e fica dentro dos insets safe-area, ou você precisa posicionar cada etapa manualmente?
- Nova Arquitetura (Fabric) — a sobreposição renderiza corretamente sem uma película branca sobre o destaque?
A opção mais instalada e aquela que a maioria das tutoriais se refere. Você envolve componentes com copilotStep/walkthroughable HOCs e inicia uma tour. Maturado e testado em batalha, com uma grande comunidade.
Trocas: as formas de destaque são básicas, a posição geralmente precisa ser ajustada manualmente e obter o funcionamento sob Expo/New Architecture pode exigir configuração adicional.
Um fork popular do copilot que usa react-native-svg para a máscara e adiciona formas de círculo/retângulo e alguns animações. Um passo significativo em termos visuais se você já está no modelo mental copilot.
Trade-offs: sem correspondência automática de forma por canto, sem rolagem automática embutida e a abordagem SVG <Mask> pode mostrar um filme leve sobre o destaque em alguns setups.
Uma biblioteca limpa e bem documentada construída ao redor de uma metáfora de spotlight com uma API baseada em hooks. Ótima se você quiser algo simples e legível.
Trade-offs: as formas do spotlight são limitadas a círculo/retângulo, e rolagem para alvos fora da tela é por sua conta.
Uma biblioteca mais recente e leve focada nas duas coisas que os outros fazem você fazer à mão: spotlights com precisão de forma e rolagem automática.
- Correspondência automática de forma — passe o mesmo estilo que você usa no componente como
targetStyle, e o spotlight lê seuborderRadiuse corresponde exatamente. Avatares circulares recebem spotlights circulares; uma bolha de bate-papo com cantos assimétricos recebe um spotlight assimétrico; um cartão comborderRadius: 12permanece 12px. - Rolagem automática inteligente — dê a ele um
scrollRefe ele rola para que o alvo e seu tooltip estejam ambos totalmente visíveis, escondendo o destaque durante a rolagem para evitar piscar. - Posicionamento inteligente de tooltips — detecta automaticamente o melhor lado e limita dentro dos insets da área segura para que nunca renderize fora da tela.
- Roda no Expo Go — zero dependências nativas (apenas
react-native-svg, que o Expo fornece). Nenhuma build personalizada do desenvolvedor necessária. - Safe para Fabric — a sobreposição é um único caminho SVG de paridade-par (um verdadeiro buraco perfurado), não um
<Mask>, então não há filme branco na Nova Arquitetura. - Tópicos tematizáveis +
createTheme(), animação de pulso, pause/resume, etapas condicionais e um hookuseTourPersistencepara "mostrar apenas uma vez".
const { startTour } = useTourGuide();
startTour([
{ id: ">welcome, targetRef: buttonRef, title: ">Bem-vindo(a), description: ">Toque aqui para começar., targetStyle:
Qual biblioteca de tour do React Native funciona com o Expo Go?
O react-native-tour-guide roda no Expo Go por padrão porque sua única dependência é react-native-svg, que já vem com o Expo Go. A maioria das alternativas precisa de configuração adicional ou um build personalizado.
Como destaco um componente com uma luz de spotlight que se ajusta à sua forma?
No react-native-tour-guide, passe o próprio objeto de estilo do componente como targetStyle — a luz de spotlight lê seu borderRadius (incluindo valores por canto) e corresponde exatamente à forma cortada. Outras bibliotecas limitam você a retângulos ou circunferências configurados.
Como rolo para um passo do tour que está fora da tela?
Passe um scrollRef ao react-native-tour-guide e ele rola automaticamente para que tanto o alvo quanto sua tooltip estejam totalmente visíveis, ocultando a destaque no meio do rolamento para evitar piscar. No copilot, rn-tourguide e spotlight-tour, rolar para alvos fora da tela é principalmente manual.
Como mostro um tour de onboarding apenas uma vez?
O react-native-tour-guide vem com o hook useTourPersistence exatamente para isso — ele registra a conclusão para que o tour só seja executado na primeira inicialização. Com outras bibliotecas, você precisaria configurar isso mesmo usando AsyncStorage.
Links: Documentação · GitHub (fonte + demonstrações) · Pacote npm — se isso economizar seu tempo, um ⭐ no GitHub ajuda outras pessoas a encontrá-lo.
Escrivi essa comparação após construir a quarta biblioteca na lista, então estou parcial mas tentei ser justo — se sua experiência com copilot, rn-tourguide ou spotlight-tour é diferente, me avise nos comentários e atualizarei o post. Curioso também: qual parte mais irritante da construção de onboarding no RN para você?