Integrando a uma Página Web

A integração do VLibras Widget com um website é feita adicionando o script abaixo em qualquer parte da página HTML:

<script src="https://vlibras.gov.br/app/vlibras-plugin.js"></script>

Apenas isso já é suficiente — o Widget é inicializado automaticamente, sem necessidade de nenhuma chamada adicional.

Caso queira personalizar o comportamento padrão da ferramenta, é possível adicionar um segundo script chamando new window.VLibras.Widget(). Essa chamada aceita dois formatos: um objeto de configuração ou os parâmetros passados diretamente, em sequência.

Passando um objeto de configuração

<script src="https://vlibras.gov.br/app/vlibras-plugin.js"></script>
<script>
  new window.VLibras.Widget({
      rootPath: 'https://vlibras.gov.br/app',
      personalization: 'https://vlibras.gov.br/config/default_logo.json',
      avatar: 'random',
      position: 'R',
  });
</script>

Passando os parâmetros diretamente

<script src="https://vlibras.gov.br/app/vlibras-plugin.js"></script>
<script>
  new window.VLibras.Widget(
    'https://vlibras.gov.br/app',
    'https://vlibras.gov.br/config/default_logo.json',
    'random',
    'R'
  );
</script>

Importante

Nesse formato, a ordem dos parâmetros deve ser respeitada: rootPath, personalization, avatar e position, nessa sequência.

Parâmetros

O VLibras Widget possibilita definir alguns valores padrão que nos permitem personalizar a ferramenta de acordo com nossas preferências. Para isso, deve-se passar um objeto (ou os parâmetros diretamente) para o construtor do Widget (new window.VLibras.Widget();) com estes valores. Confira cada um deles a seguir.

rootPath

Define o caminho da build local da aplicação. A fim de otimizar o processo de carregamento da ferramenta, você pode alocar a versão compilada do widget em seu próprio servidor e definir o link de acesso na implementação.

Importante

Esse método de implementação impede o widget no seu site receber atualizações automáticas e correções de possíveis problemas.
personalization

Define o link com as customizações personalizadas dos avatares.

Importante

A personaliação dos avatares é um rescurso exclusivo de instituições parceiras do projeto. Saiba mais em Requisitos para personalização dos avatares.
position:

Define a posição inicial do Widget. Segue a tabela com os valores disponíveis:

Valor

Posição

R (right)

Á direita (padrão)

L (left)

Á esquerda
avatar:

Define o avatar padrão. No momento, o VLibras conta com “icaro” (padrão), “hosana” e “guga”. Também é possível utilizar “random” para escolher um avatar aleatório. Se não for especificado, o Widget utilizará o avatar Icaro como padrão.

Personalizando o botão via variáveis CSS

O botão flutuante do VLibras Widget é renderizado dentro de uma shadow root, o que isola seus estilos do restante da página. Ainda assim, é possível personalizar sua aparência em alguns estados de interação através de variáveis CSS (custom properties), definidas no elemento raiz da sua aplicação (:root) ou em qualquer ancestral do Widget.

Variável	Descrição	Valor padrão
`--vlibras-btn-outline`	Contorno (outline) padrão do botão.	não definido
`--vlibras-btn-focus-visible-outline`	Contorno do botão quando focado via teclado.	`2px solid #fff`
`--vlibras-btn-focus-visible-shadow`	Sombra (box-shadow) do botão quando focado via teclado.	`0 0 10px 4px #1351b4`
`--vlibras-btn-hover-filter`	Filtro aplicado ao botão ao passar o mouse (hover).	`brightness(1.1)`

<style>
  :root {
    --vlibras-btn-focus-visible-outline: 2px solid #000;
    --vlibras-btn-focus-visible-shadow: 0 0 10px 4px #0a0;
    --vlibras-btn-hover-filter: brightness(1.2);
  }
</style>

Importante

Como essas propriedades são herdadas através da shadow root, elas devem ser definidas em um seletor que englobe o elemento onde o script do Widget foi inserido (por exemplo, :root ou body).

Além das variáveis CSS, o próprio elemento do botão fica disponível em window.VLibrasWidget.initBtn após o carregamento do Widget, permitindo manipulá-lo diretamente via JavaScript (por exemplo, para adicionar event listeners ou aplicar estilos que fogem do escopo das variáveis descritas acima).

<script>
  window.VLibrasWidget.initBtn.style.border = '2px solid #000';
</script>

Valor	Posição
R (right)	Á direita (padrão)
L (left)	Á esquerda