Por que o CSS precisa de funções personalizadas?

Durante anos, quem desenvolve com CSS dependeu de pré-processadores como Sass para trazer lógica e reutilização para os estilos. Mas agora a plataforma está evoluindo. A regra @function do CSS, parte do Módulo de Funções e Mixins Customizados Nível 1, permite definir suas próprias funções diretamente no CSS — sem necessidade de build.

Imagine poder escrever uma função que calcula uma porcentagem de progresso, ajusta o espaçamento com base em uma escala, ou até retorna uma cor com transparência. Com @function, você pode encapsular lógica complexa e reutilizá-la em todo o seu CSS.

Isso não é apenas açúcar sintático. É uma mudança fundamental para um CSS mais sustentável e com segurança de tipos. Vamos ver como funciona na prática.

Atenção: @function ainda é experimental. Verifique o suporte do navegador antes de usar em produção.

Developer writing CSS custom functions in a code editor Programming Illustration

Sintaxe Básica e Exemplos Práticos

Definindo uma função simples

Uma função personalizada começa com @function, seguida de um nome --ident, parâmetros opcionais e um descritor returns. Dentro, usamos o descritor result para retornar um valor.

/* Define uma função que divide qualquer comprimento pela metade */
@function --half(--size) returns {
  result: calc(var(--size) / 2);
}

/* Uso */
.container {
  margin-inline: --half(20px); /* 10px */
}

Verificação de tipos para segurança

Você pode forçar os tipos de entrada usando colchetes angulares, similar ao @property. Isso ajuda a evitar erros em projetos grandes.

/* Aceita apenas números e retorna porcentagem */
@function --progression(--current, --total) returns {
  result: calc(var(--current) / var(--total) * 100%);
}

.progress-bar {
  width: --progression(3, 5); /* 60% */
}

Trabalhando com listas e valores padrão

Para passar listas, use o sufixo # e envolva os valores em chaves. Valores padrão também são suportados.

/* Calcula a amplitude de uma lista mais um valor extra */
@function --get-range(--list#, --n) {
  result: calc(max(var(--list)) - min(var(--list)) + var(--n));
}

div {
  padding-block: --get-range({10px, 100px, 50px, 25px}, 200px); /* 290px */
}

Funções aninhadas e variáveis locais

Você pode aninhar funções e usar propriedades customizadas locais, mantendo o código modular e limpo.

@function --square(--n) {
  result: calc(var(--n) * var(--n));
}

@function --circle-area(--radius) {
  --pi: 3.14159;
  result: calc(var(--pi) * --square(var(--radius)));
}

.blob {
  width: calc(--circle-area(10) * 1px); /* 314.159px */
}

Usando a cascata para lógica responsiva

Como result segue a cascata do CSS, você pode usar media queries ou container queries para retornar valores diferentes.

@function --suitable-font-size() returns {
  result: 16px;
  @media (width > 1000px) {
    result: 20px;
  }
}

body {
  font-size: --suitable-font-size();
}

Lembre-se: A última declaração válida vence. Se você colocar o fallback depois da media query, ele vai sobrescrever.

CSS @function at-rule example on a laptop screen Dev Environment Setup

Limitações e Atenção

Apesar de poderoso, @function tem regras rígidas:

  • Sem efeitos colaterais: Você não pode alterar propriedades ou gerar múltiplas declarações. Isso é reservado para a proposta @mixin.
  • Dependências circulares: Se uma função chama a si mesma (direta ou indiretamente), o navegador marca como inválida. O mesmo vale para propriedades customizadas que dependem da função.
  • Mismatch de tipos: Se um argumento não corresponde ao tipo declarado, toda a chamada da função se torna inválida.

Suporte e Progressive Enhancement

Atualmente, @function só é suportado com flags em alguns navegadores. Navegadores sem suporte ignoram a regra, então use fallbacks e @supports para progressive enhancement.

@supports (at-rule(@function)) {
  /* Use funções customizadas */
}

Porém, note que a condição at-rule() em si tem suporte limitado (Chrome 148+ apenas). Para status atualizado, consulte Can I use.

CSS code snippet showing custom function syntax IT Technology Image

Conclusão e Próximos Passos

A @function do CSS é um divisor de águas para criar estilos sustentáveis e com lógica. Comece a experimentar em seus projetos locais para se familiarizar com a sintaxe e as capacidades. Quando o suporte dos navegadores melhorar, você estará pronto para adotar em produção.

Para um mergulho mais profundo em recursos modernos de CSS, confira nosso guia sobre container queries e exemplos práticos de custom properties.

Se você está interessado em como decidir entre modais e páginas separadas em UX, temos uma árvore de decisão definitiva que pode ajudar. E para quem trabalha com sistemas distribuídos, nosso tutorial de comunicação PyTorch é um ótimo recurso.

Fonte: CSS-Tricks Almanac: @function

Este conteúdo foi elaborado com o auxílio de ferramentas de IA, com base em fontes confiáveis, e revisado pela nossa equipe editorial antes da publicação. Não substitui o aconselhamento de um profissional especializado.