Propriedade CSS offset-distance

A propriedade CSS offset-distance define o quanto um elemento se move ao longo do seu caminho de movimento — o caminho definido pela propriedade offset-path. Pense no offset-path como o traçado de uma trilha, e no offset-distance como a posição do elemento nessa trilha: 0 coloca-o no início, 100% no final.

É um dos blocos de construção do CSS Motion Path, que permite que um elemento percorra uma forma arbitrária (uma linha, uma curva, um caminho SVG) em vez de ficar limitado a transições retas com top/left. Sozinho, o offset-distance é estático, mas animá-lo de 0 a 100% é o que faz o elemento deslizar ao longo do caminho.

Quando usar

Animando um elemento ao longo de um caminho curvo ou personalizado — um avião seguindo uma rota, uma conta em um fio, um ícone traçando um círculo. Transições CSS retas não conseguem fazer isso; um caminho de movimento consegue.
Pausando um elemento em um ponto específico de um caminho — defina um valor fixo como offset-distance: 50% para posicionar o elemento na metade do seu offset-path.
Movimento controlado por rolagem ou interação — atualize offset-distance com JavaScript (ou uma animação de rolagem) para mover um elemento ao longo de um caminho em resposta à entrada do usuário.

offset-distance não tem efeito a menos que o elemento também tenha um offset-path. Sem um caminho, não há nada em relação ao qual medir a distância.

Valores

Aceita um único <length-percentage>:

<length> — uma distância absoluta a partir do início do caminho, por exemplo, 40px.
<percentage> — uma distância relativa ao comprimento total do caminho. 0% é o início, 100% é o final.

O valor inicial é 0.

Informação

Valores negativos e acima de 100% são válidos. Um valor como -20% ou 120% estende o elemento além das extremidades do caminho; para um caminho fechado, ele dá a volta. Isso é útil quando você quer que um elemento comece fora do caminho e seja animado para dentro dele.

Aviso

offset-distance faz parte do módulo experimental CSS Motion Path. Nas primeiras versões da especificação, esta propriedade era chamada de motion-offset. Verifique o suporte atual dos navegadores antes de usá-la em produção.

Propriedade	Valor
Valor Inicial	`0`
Aplica-se a	Elementos transformáveis
Herdado	Não
Animável	Sim
Versão	Motion Path Module Level 1
Sintaxe DOM	`object.style.offsetDistance = "100%";`

Sintaxe

offset-distance: <length-percentage>;

Por exemplo:

/* A fixed point partway along the path */
offset-distance: 70%;

/* Absolute distance from the start */
offset-distance: 50px;

/* Animate from start to end of the path */
@keyframes move {
  to {
    offset-distance: 100%;
  }
}

Exemplos

Animando um elemento ao longo de um caminho personalizado

O elemento abaixo tem um offset-path em forma de curva. Animar offset-distance do seu valor padrão 0 até 100% faz a caixa deslizar suavemente ao longo desse caminho. Observe que offset-rotate: reverse faz a caixa girar para encarar a direção de movimento.

Exemplo representado com Casa e Tesoura

<!DOCTYPE html>
<html>
  <head>
    <title>Title of the document</title>
    <style>
      body {
        background-color: #ccc;
      }
      .mover {
        width: 80px;
        height: 80px;
        background: linear-gradient(#eee 50%, #1c87c9 50%);
        position: absolute;
        left: 20%;
        top: 100px;
        offset-path: path("M18.45,58.46s52.87-70.07,101.25-.75,101.75-6.23,101.75-6.23S246.38,5.59,165.33,9.08s-15,71.57-94.51,74.56S18.45,58.46,18.45,58.46Z");
        offset-rotate: reverse;
        animation: move 4s linear infinite;
      }
      @keyframes move {
        100% {
          offset-distance: 100%;
        }
      }
    </style>
  </head>
  <body>
    <h2>Offset-distance property example</h2>
    <div class="mover"></div>
  </body>
</html>

Experimente Você Mesmo »

Especificando a distância como uma porcentagem

Aqui o valor é animado como uma porcentagem do comprimento total do caminho, de modo que o elemento completa exatamente uma passagem completa independentemente do tamanho do caminho. Usar 100% em vez de um comprimento absoluto é a maneira mais portável de animar ao longo de um caminho.

Exemplo da propriedade CSS offset-distance

<!DOCTYPE html>
<html>
  <head>
    <title>Title of the document</title>
    <style>
      .scissorHalf {
        offset-path: path('M900,190  L993,245 V201  A11,11 0 0,1 1004,190  H1075  A11,11 0 0,1 1086,201  V300  L1294,423 H1216  A11,11 0 0,0 1205,434  V789  A11,11 0 0,1 1194,800  H606  A11,11 0 0,1 595,789  V434  A11,11 0 0,0 584,423  H506 L900,190');
        animation: followpath 4s linear infinite;
      }
      @keyframes followpath {
        to {
          offset-distance: 100%;
        }
      }
    </style>
  </head>
  <body>
    <h2>Offset-distance property example</h2>
    <svg class="box" width="700" height="450" viewBox="350 0 1400 900">
      <title>House and Scissors</title>
      <rect x="595" y="423" width="610" height="377" fill="#1c87c9" />
      <polygon points="506,423 900,190 1294,423" fill="#8ebf42" />
      <polygon points="993,245 993,190 1086,190 1086,300" fill="#666" />
      <path id="house" d="M900,190 L993,245 V201 A11,11 0 0,1 1004,190 H1075 A11,11 0 0,1 1086,201 V300 L1294,423 H1216 A11,11 0 0,0 1205,434 V789 A11,11 0 0,1 1194,800 H606 A11,11 0 0,1 595,789 V434 A11,11 0 0,0 584,423 H506 L900,190" fill="none" stroke="black" stroke-width="13" stroke-linejoin="round" stroke-linecap="round" />
      <path id="secondScissorHalf" class="scissorHalf" d="M30,0 H-10 A10,10 0 0,1 -20,-10 A20,20 0 1,0 -40,10 H20 A10,10 0 0,0 30,0 M-40,-20 A10,10 1 0,0 -40,0 A10,10 1 0,0 -40,-20 M0,0" transform="translate(0,0)" fill="forestgreen" stroke="black" stroke-width="5" stroke-linejoin="round" stroke-linecap="round" fill-rule="evenodd" />
    </svg>
  </body>
</html>

Experimente Você Mesmo »

Valores aceitos

Valor	Descrição
`<length-percentage>`	Um comprimento ou porcentagem que indica a posição ao longo do caminho de deslocamento, medida a partir do seu início.
`initial`	Define a propriedade com seu valor padrão (`0`).
`inherit`	Herda o valor do elemento pai.

Propriedades relacionadas

offset-distance raramente é usada sozinha — ela funciona em conjunto com as outras propriedades CSS Motion Path:

offset-path — define o caminho pelo qual o elemento se move.
offset-rotate — controla como o elemento gira ao seguir o caminho.
offset-anchor — escolhe qual ponto do elemento é colocado no caminho.
offset — o atalho que define todas as propriedades de motion-path de uma vez.
animation — aciona os keyframes do offset-distance que produzem o movimento.

Prática

O que a propriedade CSS 'offset-distance' permite que você faça?

Permite definir o gradiente para um fundo de gradiente linear.Permite definir a distância ao longo do caminho para posicionar o elemento.Permite definir uma margem entre dois elementos.Permite definir a rotação de um elemento.Permite posicionar um item ao longo de um caminho identificado.