useWindowSize - Acompanhe as dimensões da janela reativamente com atualizações debounced

Q: Como desativo o debounce para atualizações imediatas?

Defina debounceDelay para 0: Isso ainda usa setTimeout(..., 0) que adia para o próximo tick. Para atualizações verdadeiramente síncronas, remova o setTimeout do hook.

Q: O que faz o initialSize e quando é usado?

initialSize fornece as dimensões retornadas durante o SSR (padrão: { width: 0, height: 0 }). No cliente, o efeito atualiza imediatamente para as dimensões reais. Passe uma estimativa razoável (por exemplo, { width: 1024, height: 768 }) para reduzir a mudança de layout.

Q: Armadilha: Minha página SSR mostra uma mudança de layout porque o servidor renderiza com largura 0. Como corrijo isso?

Passe um initialSize realista que corresponda à sua viewport mais comum. Para layouts críticos, prefira media queries CSS que não dependem de JavaScript. Use useMediaQuery para verificações booleanas de ponto de interrupção que toleram o breve flash.

Q: Como este hook difere de useMediaQuery para layouts responsivos?

useWindowSize retorna valores exatos em pixels (width, height). useMediaQuery retorna um booleano para um ponto de interrupção específico. Use useWindowSize quando precisar de cálculos (por exemplo, dimensionamento de tela, contagem de colunas). Use useMediaQuery quando precisar apenas de um alternador booleano.

Q: Posso rastrear a altura total de rolagem do documento em vez da viewport?

Sim. Substitua window.innerWidth/Height por document.documentElement.scrollWidth/Height dentro do manipulador de redimensionamento. Isso fornece o tamanho total do documento, incluindo o overflow.

Q: Qual é o tipo TypeScript do objeto retornado?

O hook retorna WindowSize, que é { width: number; height: number }. A interface é exportada para que os consumidores possam usá-la para seus próprios tipos de props ou estado.

Receita

import { useState, useEffect, useCallback, useRef } from "react";
 
interface WindowSize {
  width: number;
  height: number;
}
 
interface UseWindowSizeOptions {
  /** Atraso do debounce em ms. Padrão: 100 */
  debounceDelay?: number;
  /** Tamanho inicial para SSR. Padrão: { width: 0, height: 0 } */
  initialSize?: WindowSize;
}
 
function useWindowSize(options: UseWindowSizeOptions = {}): WindowSize {
  const {
    debounceDelay = 100,
    initialSize = { width: 0, height: 0 },
  } = options;
 
  const [size, setSize] = useState<WindowSize>(() => {
    // Inicializador preguiçoso: lê as dimensões da janela apenas no cliente
    if (typeof window === "undefined") return initialSize;
    return {
      width: window.innerWidth,
      height: window.innerHeight,
    };
  });
 
  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
  useEffect(() => {
    // Não faz nada no servidor
    if (typeof window === "undefined") return;
 
    const handleResize = () => {
      // Limpa qualquer timer pendente
      if (timerRef.current) clearTimeout(timerRef.current);
 
      // Define um novo timer para atualizar o tamanho após o atraso do debounce
      timerRef.current = setTimeout(() => {
        setSize({
          width: window.innerWidth,
          height: window.innerHeight,
        });
        timerRef.current = null; // Limpa a referência do timer após a execução
      }, debounceDelay);
    };
 
    // Define o tamanho inicial ao montar para garantir que o estado esteja atualizado
    setSize({
      width: window.innerWidth,
      height: window.innerHeight,
    });
 
    // Adiciona o listener de evento de redimensionamento
    window.addEventListener("resize", handleResize);
 
    // Função de limpeza para remover o listener e limpar o timer
    return () => {
      window.removeEventListener("resize", handleResize);
      if (timerRef.current) clearTimeout(timerRef.current);
    };
  }, [debounceDelay]); // Reexecuta o efeito se debounceDelay mudar
 
  return size;
}

Quando usar isso: Você precisa das dimensões da janela em JavaScript para cálculos de layout responsivo, dimensionamento de tela, listas virtualizadas ou renderização condicional que as media queries CSS não conseguem lidar.

Exemplo de Trabalho

"use client";
 
function ResponsiveLayout() {
  const { width, height } = useWindowSize();
 
  // Determina o número de colunas com base na largura da janela
  const columns = width >= 1024 ? 3 : width >= 640 ? 2 : 1;
 
  return (
    <div>
      <p>
        Janela: {width} x {height}
      </p>
      <div
        style={{
          display: "grid",
          gridTemplateColumns: `repeat(${columns}, 1fr)`,
          gap: 16,
        }}
      >
        {Array.from({ length: 6 }, (_, i) => (
          <div
            key={i}
            style={{
              padding: 24,
              background: "#f5f5f5",
              borderRadius: 8,
              textAlign: "center",
            }}
          >
            Card {i + 1}
          </div>
        ))}
      </div>
    </div>
  );
}
 
function CanvasSizer() {
  // Usa um atraso de debounce maior para o componente de tela
  const { width } = useWindowSize({ debounceDelay: 200 });
 
  // Calcula a largura e altura da tela mantendo a proporção 16:9
  const canvasWidth = Math.min(width - 32, 800);
  const canvasHeight = canvasWidth * 0.5625; // Proporção 16:9
 
  return (
    <canvas
      width={canvasWidth}
      height={canvasHeight}
      style={{ border: "1px solid #ccc" }}
    />
  );
}

O que isso demonstra:

A contagem de colunas da grade se adapta com base nos pontos de interrupção da largura da janela.
A tela mantém uma proporção de 16:9 em relação à largura da janela.
O debounce evita renderizações excessivas durante o arrasto de redimensionamento.
Atraso de debounce personalizado para o componente de tela (200 ms).

Mergulho Profundo

Como Funciona

Inicializador preguiçoso: useState lê window.innerWidth e window.innerHeight apenas no cliente, retornando initialSize durante o SSR.
Manipulador de redimensionamento debounced: Um debounce baseado em setTimeout colapsa eventos rápidos de redimensionamento em uma única atualização de estado, prevenindo travamentos.
Limpeza: O listener de evento e qualquer timer pendente são limpos ao desmontar.
Ressincronização ao montar: O efeito define imediatamente o tamanho atual para lidar com casos em que a janela foi redimensionada enquanto o componente estava desmontado.

Parâmetros e Valores de Retorno

Opção	Tipo	Padrão	Descrição
`debounceDelay`	`number`	`100`	Milissegundos para debouncing de eventos de redimensionamento
`initialSize`	`{ width, height }`	`{ width: 0, height: 0 }`	Tamanho retornado durante o SSR

Retorno	Tipo	Descrição
`width`	`number`	`window.innerWidth` atual
`height`	`number`	`window.innerHeight` atual

Variações

Sem debounce: Para atualizações imediatas (por exemplo, pré-visualizações de redimensionamento por arrasto), defina debounceDelay: 0 ou remova o setTimeout:

const size = useWindowSize({ debounceDelay: 0 });

Com orientação: Detecte paisagem vs. retrato:

function useOrientation() {
  const { width, height } = useWindowSize();
  return width > height ? "landscape" : "portrait";
}

Tamanho do documento (altura de rolagem): Acompanhe a altura total do documento em vez da viewport:

// Dentro do manipulador de redimensionamento:
setSize({
  width: document.documentElement.scrollWidth,
  height: document.documentElement.scrollHeight,
});

Notas TypeScript

A interface WindowSize é exportada para que os consumidores possam tipar seu próprio estado ou props.
Nenhum genérico é necessário; o tipo de retorno é sempre { width: number; height: number }.
A interface de opções usa propriedades opcionais com padrões desestruturados no corpo da função.

Armadilhas

Dessincronização de hidratação SSR - O servidor renderiza com initialSize (0x0), mas o cliente atualiza imediatamente para as dimensões reais. Correção: Isso causa uma mudança de layout na primeira renderização. Para layouts críticos, prefira media queries CSS ou forneça uma estimativa razoável de initialSize.
Atualizações muito frequentes - Sem debounce, cada pixel de um arrasto de redimensionamento aciona uma re-renderização. Correção: O debounce integrado lida com isso; ajuste debounceDelay conforme necessário.
Teclado virtual em dispositivos móveis - Em dispositivos móveis, abrir o teclado redimensiona a viewport e aciona o manipulador. Correção: Use a API window.visualViewport se precisar distinguir o teclado de um redimensionamento real da janela.
Contexto iframe - Dentro de um iframe, window.innerWidth reflete o tamanho do iframe, não da janela pai. Correção: Use parent.window se a política de origem cruzada permitir, ou passe o tamanho como uma prop.

Alternativas

Pacote	Nome do Hook	Notas
`usehooks-ts`	`useWindowSize`	Sem debounce integrado
`@uidotdev/usehooks`	`useWindowSize`	Implementação mínima
`ahooks`	`useSize`	Rastreia qualquer elemento, não apenas a janela
`react-use`	`useWindowSize`	Inclui padrões do lado do servidor
`@react-hook/window-size`	`useWindowSize`	Variante com throttling disponível

FAQs

Por que o hook debounces os eventos de redimensionamento por padrão?

Sem debounce, cada pixel de um arrasto de redimensionamento aciona uma atualização de estado e re-renderização. O debounce integrado colapsa eventos rápidos em uma única atualização, prevenindo travamentos e renderizações desperdiçadas.

Como desativo o debounce para atualizações imediatas?

Defina debounceDelay para 0:

const size = useWindowSize({ debounceDelay: 0 });

Isso ainda usa setTimeout(..., 0) que adia para o próximo tick. Para atualizações verdadeiramente síncronas, remova o setTimeout do hook.

O que faz o initialSize e quando é usado?

initialSize fornece as dimensões retornadas durante o SSR (padrão: { width: 0, height: 0 }).
No cliente, o efeito atualiza imediatamente para as dimensões reais.
Passe uma estimativa razoável (por exemplo, { width: 1024, height: 768 }) para reduzir a mudança de layout.

Por que o efeito define o tamanho imediatamente ao montar, além de ouvir o redimensionamento?

O componente pode ter sido desmontado e remontado enquanto a janela era redimensionada. A definição imediata garante que o estado esteja correto, mesmo que nenhum evento de redimensionamento ocorra após a montagem.

Armadilha: Minha página SSR mostra uma mudança de layout porque o servidor renderiza com largura 0. Como corrijo isso?

Passe um initialSize realista que corresponda à sua viewport mais comum.
Para layouts críticos, prefira media queries CSS que não dependem de JavaScript.
Use useMediaQuery para verificações booleanas de ponto de interrupção que toleram o breve flash.

Armadilha: Abrir o teclado em dispositivos móveis dispara um evento de redimensionamento e re-renderiza meu layout. Por quê?

Em navegadores móveis, o teclado virtual redimensiona a viewport. O hook dispara em qualquer redimensionamento, incluindo a abertura/fechamento do teclado. Use a API window.visualViewport para distinguir eventos de teclado de redimensionamentos reais da janela.

Como este hook difere de useMediaQuery para layouts responsivos?

useWindowSize retorna valores exatos em pixels (width, height).
useMediaQuery retorna um booleano para um ponto de interrupção específico.
Use useWindowSize quando precisar de cálculos (por exemplo, dimensionamento de tela, contagem de colunas).
Use useMediaQuery quando precisar apenas de um alternador booleano.

Posso rastrear a altura total de rolagem do documento em vez da viewport?

Sim. Substitua window.innerWidth/Height por document.documentElement.scrollWidth/Height dentro do manipulador de redimensionamento. Isso fornece o tamanho total do documento, incluindo o overflow.

Qual é o tipo TypeScript do objeto retornado?

O hook retorna WindowSize, que é { width: number; height: number }. A interface é exportada para que os consumidores possam usá-la para seus próprios tipos de props ou estado.

Como eu construiria um hook useOrientation em cima de useWindowSize?

function useOrientation(): "landscape" | "portrait" {
  const { width, height } = useWindowSize();
  return width > height ? "landscape" : "portrait";
}

Relacionados

useMediaQuery - verificações booleanas de ponto de interrupção
useDebounce - o padrão de debounce em detalhes
useEventListener - vinculação declarativa de eventos

Receita

import { useState, useEffect, useCallback, useRef } from "react";
 
interface WindowSize {
  width: number;
  height: number;
}
 
interface UseWindowSizeOptions {
  /** Atraso do debounce em ms. Padrão: 100 */
  debounceDelay?: number;
  /** Tamanho inicial para SSR. Padrão: { width: 0, height: 0 } */
  initialSize?: WindowSize;
}
 
function useWindowSize(options: UseWindowSizeOptions = {}): WindowSize {
  const {
    debounceDelay = 100,
    initialSize = { width: 0, height: 0 },
  } = options;
 
  const [size, setSize] = useState<WindowSize>(() => {
    // Inicializador preguiçoso: lê as dimensões da janela apenas no cliente
    if (typeof window === "undefined") return initialSize;
    return {
      width: window.innerWidth,
      height: window.innerHeight,
    };
  });
 
  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
  useEffect(() => {
    // Não faz nada no servidor
    if (typeof window === "undefined") return;
 
    const handleResize = () => {
      // Limpa qualquer timer pendente
      if (timerRef.current) clearTimeout(timerRef.current);
 
      // Define um novo timer para atualizar o tamanho após o atraso do debounce
      timerRef.current = setTimeout(() => {
        setSize({
          width: window.innerWidth,
          height: window.innerHeight,
        });
        timerRef.current = null; // Limpa a referência do timer após a execução
      }, debounceDelay);
    };
 
    // Define o tamanho inicial ao montar para garantir que o estado esteja atualizado
    setSize({
      width: window.innerWidth,
      height: window.innerHeight,
    });
 
    // Adiciona o listener de evento de redimensionamento
    window.addEventListener("resize", handleResize);
 
    // Função de limpeza para remover o listener e limpar o timer
    return () => {
      window.removeEventListener("resize", handleResize);
      if (timerRef.current) clearTimeout(timerRef.current);
    };
  }, [debounceDelay]); // Reexecuta o efeito se debounceDelay mudar
 
  return size;
}

Exemplo de Trabalho

"use client";
 
function ResponsiveLayout() {
  const { width, height } = useWindowSize();
 
  // Determina o número de colunas com base na largura da janela
  const columns = width >= 1024 ? 3 : width >= 640 ? 2 : 1;
 
  return (
    <div>
      <p>
        Janela: {width} x {height}
      </p>
      <div
        style={{
          display: "grid",
          gridTemplateColumns: `repeat(${columns}, 1fr)`,
          gap: 16,
        }}
      >
        {Array.from({ length: 6 }, (_, i) => (
          <div
            key={i}
            style={{
              padding: 24,
              background: "#f5f5f5",
              borderRadius: 8,
              textAlign: "center",
            }}
          >
            Card {i + 1}
          </div>
        ))}
      </div>
    </div>
  );
}
 
function CanvasSizer() {
  // Usa um atraso de debounce maior para o componente de tela
  const { width } = useWindowSize({ debounceDelay: 200 });
 
  // Calcula a largura e altura da tela mantendo a proporção 16:9
  const canvasWidth = Math.min(width - 32, 800);
  const canvasHeight = canvasWidth * 0.5625; // Proporção 16:9
 
  return (
    <canvas
      width={canvasWidth}
      height={canvasHeight}
      style={{ border: "1px solid #ccc" }}
    />
  );
}

O que isso demonstra:

A contagem de colunas da grade se adapta com base nos pontos de interrupção da largura da janela.
A tela mantém uma proporção de 16:9 em relação à largura da janela.
O debounce evita renderizações excessivas durante o arrasto de redimensionamento.
Atraso de debounce personalizado para o componente de tela (200 ms).

Mergulho Profundo

Como Funciona

Inicializador preguiçoso: useState lê window.innerWidth e window.innerHeight apenas no cliente, retornando initialSize durante o SSR.
Manipulador de redimensionamento debounced: Um debounce baseado em setTimeout colapsa eventos rápidos de redimensionamento em uma única atualização de estado, prevenindo travamentos.
Limpeza: O listener de evento e qualquer timer pendente são limpos ao desmontar.
Ressincronização ao montar: O efeito define imediatamente o tamanho atual para lidar com casos em que a janela foi redimensionada enquanto o componente estava desmontado.

Parâmetros e Valores de Retorno

Opção	Tipo	Padrão	Descrição
`debounceDelay`	`number`	`100`	Milissegundos para debouncing de eventos de redimensionamento
`initialSize`	`{ width, height }`	`{ width: 0, height: 0 }`	Tamanho retornado durante o SSR

Retorno	Tipo	Descrição
`width`	`number`	`window.innerWidth` atual
`height`	`number`	`window.innerHeight` atual

Variações

Sem debounce: Para atualizações imediatas (por exemplo, pré-visualizações de redimensionamento por arrasto), defina debounceDelay: 0 ou remova o setTimeout:

const size = useWindowSize({ debounceDelay: 0 });

Com orientação: Detecte paisagem vs. retrato:

function useOrientation() {
  const { width, height } = useWindowSize();
  return width > height ? "landscape" : "portrait";
}

Tamanho do documento (altura de rolagem): Acompanhe a altura total do documento em vez da viewport:

// Dentro do manipulador de redimensionamento:
setSize({
  width: document.documentElement.scrollWidth,
  height: document.documentElement.scrollHeight,
});

Notas TypeScript

A interface WindowSize é exportada para que os consumidores possam tipar seu próprio estado ou props.
Nenhum genérico é necessário; o tipo de retorno é sempre { width: number; height: number }.
A interface de opções usa propriedades opcionais com padrões desestruturados no corpo da função.

Armadilhas

Dessincronização de hidratação SSR - O servidor renderiza com initialSize (0x0), mas o cliente atualiza imediatamente para as dimensões reais. Correção: Isso causa uma mudança de layout na primeira renderização. Para layouts críticos, prefira media queries CSS ou forneça uma estimativa razoável de initialSize.
Atualizações muito frequentes - Sem debounce, cada pixel de um arrasto de redimensionamento aciona uma re-renderização. Correção: O debounce integrado lida com isso; ajuste debounceDelay conforme necessário.
Teclado virtual em dispositivos móveis - Em dispositivos móveis, abrir o teclado redimensiona a viewport e aciona o manipulador. Correção: Use a API window.visualViewport se precisar distinguir o teclado de um redimensionamento real da janela.
Contexto iframe - Dentro de um iframe, window.innerWidth reflete o tamanho do iframe, não da janela pai. Correção: Use parent.window se a política de origem cruzada permitir, ou passe o tamanho como uma prop.

Alternativas

Pacote	Nome do Hook	Notas
`usehooks-ts`	`useWindowSize`	Sem debounce integrado
`@uidotdev/usehooks`	`useWindowSize`	Implementação mínima
`ahooks`	`useSize`	Rastreia qualquer elemento, não apenas a janela
`react-use`	`useWindowSize`	Inclui padrões do lado do servidor
`@react-hook/window-size`	`useWindowSize`	Variante com throttling disponível

FAQs

Por que o hook debounces os eventos de redimensionamento por padrão?

Como desativo o debounce para atualizações imediatas?

Defina debounceDelay para 0:

const size = useWindowSize({ debounceDelay: 0 });

Isso ainda usa setTimeout(..., 0) que adia para o próximo tick. Para atualizações verdadeiramente síncronas, remova o setTimeout do hook.

O que faz o initialSize e quando é usado?

initialSize fornece as dimensões retornadas durante o SSR (padrão: { width: 0, height: 0 }).
No cliente, o efeito atualiza imediatamente para as dimensões reais.
Passe uma estimativa razoável (por exemplo, { width: 1024, height: 768 }) para reduzir a mudança de layout.

Por que o efeito define o tamanho imediatamente ao montar, além de ouvir o redimensionamento?

Armadilha: Minha página SSR mostra uma mudança de layout porque o servidor renderiza com largura 0. Como corrijo isso?

Passe um initialSize realista que corresponda à sua viewport mais comum.
Para layouts críticos, prefira media queries CSS que não dependem de JavaScript.
Use useMediaQuery para verificações booleanas de ponto de interrupção que toleram o breve flash.

Armadilha: Abrir o teclado em dispositivos móveis dispara um evento de redimensionamento e re-renderiza meu layout. Por quê?

Como este hook difere de useMediaQuery para layouts responsivos?

useWindowSize retorna valores exatos em pixels (width, height).
useMediaQuery retorna um booleano para um ponto de interrupção específico.
Use useWindowSize quando precisar de cálculos (por exemplo, dimensionamento de tela, contagem de colunas).
Use useMediaQuery quando precisar apenas de um alternador booleano.

Posso rastrear a altura total de rolagem do documento em vez da viewport?

Qual é o tipo TypeScript do objeto retornado?

O hook retorna WindowSize, que é { width: number; height: number }. A interface é exportada para que os consumidores possam usá-la para seus próprios tipos de props ou estado.

Como eu construiria um hook useOrientation em cima de useWindowSize?

function useOrientation(): "landscape" | "portrait" {
  const { width, height } = useWindowSize();
  return width > height ? "landscape" : "portrait";
}

Relacionados

useMediaQuery - verificações booleanas de ponto de interrupção
useDebounce - o padrão de debounce em detalhes
useEventListener - vinculação declarativa de eventos

useWindowSize - Acompanhe as dimensões da janela reativamente com atualizações debounced

Buscar na documentação

useWindowSize - Acompanhe as dimensões da janela reativamente com atualizações debounced