Você já desenvolveu uma funcionalidade incrível, testou tudo, fez o deploy — e mesmo assim os usuários continuam abrindo tickets perguntando como usar? Esse é um problema clássico de onboarding. E a solução pode estar em uma biblioteca JavaScript leve, gratuita e poderosa: o Shepherd.js.

Neste artigo, você vai aprender o que são product tours, por que eles importam estrategicamente, e como implementar um tour completo com Shepherd.js do zero — incluindo integração com React e boas práticas de uso.

O que são Product Tours?

Product tours são guias interativos, passo a passo, que aparecem diretamente na interface da aplicação para orientar o usuário pelas funcionalidades do produto. Eles funcionam destacando elementos da tela, exibindo tooltips explicativos e conduzindo o usuário por um fluxo específico — tudo sem sair da aplicação.

O impacto é direto: estudos mostram que um onboarding bem estruturado pode aumentar a retenção de usuários em até 50%. De acordo com o relatório da Userpilot de 2024, empresas que implementam onboarding guiado têm 2,6x mais chances de expandir receita e reduzem tickets de suporte em até 40%.

Ou seja: product tour não é detalhe de UX. É uma decisão de negócio.

Por que Shepherd.js?

Existem diversas alternativas no mercado — Intro.js, Driver.js, Appcues, UserGuiding. O Shepherd.js se destaca pelos seguintes motivos:

• Open-source e gratuito: sem custos de licenciamento, sem planos mensais
• Leve: ~30KB gzipped, sem dependências externas pesadas
• Altamente customizável: estilização completa via CSS com classes BEM
• Acessível por padrão: suporte a ARIA, navegação por teclado e foco automático
• Compatível com qualquer stack: React, Vue, Angular, Svelte ou vanilla JS
• Posicionamento inteligente: usa o Floating UI para calcular a melhor posição dos tooltips automaticamente

Com mais de 12 mil estrelas no GitHub, é uma solução madura e com comunidade ativa.

Instalação

npm install shepherd.js

Ou via CDN:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/shepherd.js/dist/css/shepherd.css"/>
<script src="https://cdn.jsdelivr.net/npm/shepherd.js/dist/js/shepherd.min.js"></script>

Anatomia de um Tour

Um tour no Shepherd.js é composto por steps (passos). Cada step possui:

Quando um step está ativo, um overlay escurece o restante da página, direcionando a atenção do usuário ao elemento destacado.

Implementação Básica (Vanilla JS)

import Shepherd from 'shepherd.js';
import 'shepherd.js/dist/css/shepherd.css';

const tour = new Shepherd.Tour({
  useModalOverlay: true,
  defaultStepOptions: {
    cancelIcon: { enabled: true },
    classes: 'shepherd-theme-custom',
    scrollTo: { behavior: 'smooth', block: 'center' }
  }
});

tour.addStep({
  id: 'step-dashboard',
  title: 'Painel Principal',
  text: 'Este é o seu painel. Aqui você acompanha todas as métricas em tempo real.',
  attachTo: {
    element: '#dashboard',
    on: 'bottom'
  },
  buttons: [
    {
      text: 'Próximo',
      action: tour.next
    }
  ]
});

tour.addStep({
  id: 'step-criar-relatorio',
  title: 'Criar Relatório',
  text: 'Clique aqui para gerar um novo relatório em PDF ou Excel.',
  attachTo: {
    element: '.btn-criar-relatorio',
    on: 'right'
  },
  buttons: [
    { text: 'Voltar', action: tour.back, secondary: true },
    { text: 'Próximo', action: tour.next }
  ]
});

tour.addStep({
  id: 'step-configuracoes',
  title: 'Configurações',
  text: 'Personalize sua conta, notificações e preferências de exibição.',
  attachTo: {
    element: '#menu-configuracoes',
    on: 'left'
  },
  buttons: [
    { text: 'Voltar', action: tour.back, secondary: true },
    { text: 'Concluir', action: tour.complete }
  ]
});

tour.start();

Em menos de 30 linhas de código, você tem um tour funcional com overlay, navegação e botões configurados.

Integração com React

O Shepherd.js oferece o wrapper oficial react-shepherd, que expõe hooks para gerenciar o tour dentro dos componentes React.

npm install react-shepherd

import { useContext } from 'react';
import { ShepherdTour, ShepherdTourContext } from 'react-shepherd';
import 'shepherd.js/dist/css/shepherd.css';

const tourOptions = {
  useModalOverlay: true,
  defaultStepOptions: {
    cancelIcon: { enabled: true },
    scrollTo: true
  }
};

const steps = [
  {
    id: 'intro',
    title: 'Bem-vindo!',
    text: 'Vamos te mostrar as principais funcionalidades da plataforma.',
    buttons: [{ text: 'Começar', action() { return this.next(); } }]
  },
  {
    id: 'funcionalidade-principal',
    title: 'Funcionalidade Principal',
    text: 'Esta é a área central do sistema. Tudo começa aqui.',
    attachTo: { element: '#main-feature', on: 'bottom' },
    buttons: [
      { text: 'Voltar', action() { return this.back(); }, secondary: true },
      { text: 'Concluir', action() { return this.complete(); } }
    ]
  }
];

function TourButton() {
  const tour = useContext(ShepherdTourContext);
  return (
    <button onClick={() => tour.start()}>
      Iniciar Tour
    </button>
  );
}

export default function App() {
  return (
    <ShepherdTour steps={steps} tourOptions={tourOptions}>
      <TourButton />
      {/* restante da aplicação */}
    </ShepherdTour>
  );
}

O padrão de Context + hook torna o controle do tour totalmente integrado ao ciclo de vida do React.

Eventos e Callbacks

O Shepherd.js expõe eventos em cada etapa do tour, permitindo executar lógica personalizada:

tour.on('complete', () => {
  // Tour concluído — salvar no backend ou no localStorage
  localStorage.setItem('tour_concluido', 'true');
  analytics.track('tour_completed');
});

tour.on('cancel', () => {
  analytics.track('tour_cancelled', {
    step: tour.getCurrentStep()?.id
  });
});

// Em cada step individualmente
tour.addStep({
  id: 'step-relatorio',
  // ...
  when: {
    show() {
      analytics.track('tour_step_shown', { step: 'step-relatorio' });
    },
    hide() {
      console.log('Step ocultado');
    }
  }
});

Esses callbacks são essenciais para medir o engajamento real com o tour e identificar em qual passo a maioria dos usuários desiste.

Tours Condicionais

Uma prática avançada e muito útil é exibir tours diferentes dependendo do perfil do usuário ou de feature flags:

function iniciarTourPorPerfil(usuario) {
  if (usuario.role === 'admin') {
    iniciarTourAdmin();
  } else if (usuario.role === 'editor') {
    iniciarTourEditor();
  } else {
    iniciarTourBasico();
  }
}

// Verificar se o tour já foi visto antes de iniciar
function iniciarTourSeNecessario(usuario) {
  const tourVisto = localStorage.getItem(`tour_${usuario.id}`);

  if (!tourVisto) {
    iniciarTourPorPerfil(usuario);
    localStorage.setItem(`tour_${usuario.id}`, 'true');
  }
}

Você pode usar a mesma lógica com feature flags — por exemplo, exibir um tour de uma funcionalidade nova apenas para os usuários que têm acesso a ela.

Customização com CSS

O Shepherd.js usa classes BEM, o que torna a estilização previsível e fácil de sobrescrever:

/* Tooltip principal */
.shepherd-element {
  border-radius: 8px;
  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.15);
  max-width: 360px;
}

/* Cabeçalho */
.shepherd-header {
  background-color: #1d4ed8;
  padding: 16px 20px;
  border-radius: 8px 8px 0 0;
}

.shepherd-title {
  color: #ffffff;
  font-size: 16px;
  font-weight: 600;
}

/* Corpo do tooltip */
.shepherd-text {
  padding: 16px 20px;
  font-size: 14px;
  line-height: 1.6;
  color: #374151;
}

/* Botões */
.shepherd-button {
  background-color: #1d4ed8;
  color: #fff;
  border: none;
  border-radius: 6px;
  padding: 8px 16px;
  cursor: pointer;
  font-size: 14px;
  transition: background-color 0.2s;
}

.shepherd-button:hover {
  background-color: #1e40af;
}

.shepherd-button-secondary {
  background-color: transparent;
  color: #6b7280;
  border: 1px solid #d1d5db;
}

/* Overlay */
.shepherd-modal-overlay-container {
  opacity: 0.6;
}

O resultado é um tour que parece uma extensão natural da sua aplicação — não um plugin de terceiros.

Boas Práticas

Antes de colocar um tour em produção, leve em consideração:

1. Tours curtos: idealmente de 3 a 5 passos por fluxo. Tours longos cansam e aumentam a taxa de abandono.
2. Sempre ofereça saída: o usuário deve poder pular ou fechar o tour a qualquer momento.
3. Linguagem focada no benefício: prefira “Clique aqui para exportar seu relatório” ao invés de “Este é o botão de exportar”.
4. Ativação contextual: nem todo tour deve aparecer no primeiro login. Tours de funcionalidades específicas fazem mais sentido quando o usuário acessa aquela área pela primeira vez.
5. Não repita tours concluídos: salve o estado no backend ou no localStorage e verifique antes de iniciar.
6. Meça o engajamento: use os callbacks de evento para rastrear início, conclusão e abandono. Esses dados vão te dizer se o tour está funcionando ou se precisa de ajustes.

Conclusão

Shepherd.js é uma escolha sólida para qualquer equipe que queira melhorar o onboarding de seus produtos sem abrir mão de controle, personalização e acessibilidade. É gratuito, leve, bem documentado e integra naturalmente com os principais frameworks do mercado.

Mais do que uma biblioteca, product tours representam uma filosofia: a de que o usuário não deve ser deixado sozinho para descobrir o produto. Cada feature que você desenvolveu com esforço merece ser descoberta — e um bom tour é a ponte entre o que foi construído e o valor que o usuário efetivamente recebe.

Se a sua aplicação ainda não tem um product tour, este é um bom momento para começar.

Recursos úteis: – Documentação oficial do Shepherd.js – Repositório no GitHub – react-shepherd no npm