Pular para o conteúdo
Gráfico

ChartContainer

/componentes/chart-container.mdmarkdown cru, para quem lê com agent em vez de olho

Linha

Conteúdo carregado

Vazio, com saída

Conteúdo carregado

Nenhum pedido em março

O gráfico começa a desenhar assim que a loja receber o primeiro pedido.

Erro, dizendo qual gráfico falhou

Área com gradiente

Conteúdo carregado

Barra

Conteúdo carregado

Barra empilhada

Conteúdo carregado

Barra deitada, com rótulo

Conteúdo carregado

Radar

Conteúdo carregado

Dispersão

Conteúdo carregado

Vazio sem empty: o aviso curto

Conteúdo carregado

Sem dados no período

Três séries

  • Pagas
  • Abertas
  • Vencidas

Com duas séries

Agosto

  • Pedidos63
  • Entregues47

Com valor formatado

Junho

  • AssinaturasR$ 62K
Importar
import { ChartContainer } from '@rivocode/ui/chart'

Quando usar

A moldura de todo gráfico, sobre a Recharts. Vive em @rivocode/ui/chart.

Ela publica uma variável de CSS por série, com o nome da série: pedidos no config vira var(--color-pedidos), então a linha, a barra e a dica falam do mesmo jeito e trocar a cor é mexer num lugar só. Sem cor declarada, entra a próxima da paleta de oito na ordem do config.

A Recharts não lê classe do Tailwind e não conhece os nossos tokens, então a ponte tem que ser por variável. Escrever a cor direta no stroke funciona até o tema mudar.

O que não é série também sai vestido, sem token por prop: a grade, os eixos e o texto do gráfico cartesiano, e os mesmos papéis no polar e no resto. A PolarGrid pinta em --rc-chart-grid; o traço da PolarAngleAxis e da PolarRadiusAxis em --rc-border, e o texto delas em --rc-fg-subtle; o fundo da RadialBar (background) no trilho, --rc-skeleton; o contorno entre as fatias da Pie em --rc-surface; a ReferenceArea em --rc-accent-subtle; e o texto da LabelList em --rc-fg-muted. A moldura só preenche o papel que a marca deixou vago: o stroke, o fill ou o tick que você escreve vencem.

A altura fica com quem usa, por classe: gráfico sem altura definida some, porque o contentor mede o pai. Onde a moldura mede largura e nenhuma altura, ela avisa no console em desenvolvimento em vez de entregar um cartão vazio. O aviso espera o layout assentar antes de acusar, porque a caixa mede zero por um quadro no caminho normal.

Os quatro finais de uma consulta

Os mesmos do DataTable, e o empty é o mesmo objeto: title, description, action e icon. A ação é fortemente recomendada: um gráfico que só diz "sem dados" empurra para a pessoa o trabalho de adivinhar o que fazer.

<ChartContainer
  config={config}
  className="h-64"
  isLoading={query.isLoading}
  isError={query.isError}
  onRetry={query.refetch}
  empty={{
    title: 'Nenhum pedido em março',
    description: 'O gráfico começa a desenhar assim que a loja receber o primeiro pedido.',
    action: <Button size="sm">Divulgar a loja</Button>,
  }}
>
  <LineChart data={meses}>{/* ... */}</LineChart>
</ChartContainer>

O erro diz o que falhou. errorTitle e errorMessage são o par: num painel de quatro gráficos, "Não foi possível carregar o gráfico" quatro vezes não diz qual deles caiu, e num produto que não fala português não diz nada. Sem eles, o texto padrão continua o de sempre. Os dois nomes são os mesmos do DataTable, de propósito, e atravessam para o React Native com os mesmos padrões. Só o tipo estreita para string, porque o título do Alert nativo é um Text.

O erro que ocupa a seção leva desenho. errorIllustration troca o aviso pelo Result de perigo, com o desenho em cima (ServerError, ou o Bacalhau triste em produto da RivoCode) e o botão do onRetry embaixo. O gráfico pequeno, num painel de quatro, fica no aviso. O nome é o mesmo do QueryBoundary e do DataTable, e atravessa para o React Native.

O botão de nova tentativa também se traduz. labels.retry (padrão "Tentar de novo") nomeia o botão que executa o onRetry, com a mesma chave e o mesmo padrão nas peças de consulta. Num painel em outra língua, traduza os dois: o título e o botão.

A espera se anuncia em voz alta. aria-busy num nó sem papel não é lido por leitor de tela nenhum: ele descreve o estado de uma região, e só chega a quem já está dentro dela. As quatro irmãs publicam a mesma região viva (role="status" aria-live="polite", marcada com data-rc-status), que diz "Carregando…" enquanto a consulta não volta e "Conteúdo carregado" quando ela volta. Ela existe antes de o texto mudar e é o mesmo nó do primeiro ao último estado: região que nasce já com o texto dentro não dispara anúncio nenhum.

A moldura tem duas regiões vivas, e elas convivem: a do ponto ativo, que copia a dica quando a Recharts anda de ponto em ponto pelo teclado, e a da espera. data-rc-status e data-rc-active-point separam uma da outra.

A contagem de pontos sai do próprio gráfico. A moldura lê o data do filho da Recharts, então na forma acima não é preciso repeti-lo. Passe data aqui só quando os pontos não morarem no filho direto (<ScatterChart> com o data no <Scatter>) ou quando a série desenhada não for a que decide o vazio.

Onde a moldura não acha ponto para contar, ela avisa no console em desenvolvimento em vez de calar.

Sem empty, a lista vazia mostra um aviso curto, "Sem dados no período", no lugar dos eixos sobre o nada. O texto troca por labels.noData. O empty continua sendo o caminho certo quando a tela sabe dizer o porquê e a saída.

A chave do config vira o nome da variável, var(--color-<chave>), quando ela é feita de letra, número, - e _. Chave com espaço, ponto ou barra ("Receita total", "v1.2") não é nome de variável de CSS válido, então a moldura troca o que não serve por _ e acrescenta um sufixo curto que separa "a b" de "a.b"; ela, a legenda e a dica usam o mesmo nome, e nada muda para quem pinta pela moldura. Para escrever var(--color-...) à mão, prefira chave simples.

A revalidação: isFetching e isRefetchError

Os mesmos dois nomes e o mesmo desenho do QueryBoundary. Com os pontos (o data, ou o do gráfico filho) na mão, isFetching deixa o gráfico na tela, marca a moldura com aria-busy e corre uma barra fina no topo; sem dado, ele é a primeira busca, e quem desenha é o carregando. isRefetchError com os pontos (o data, ou o do gráfico filho) na mão vence o isError: o gráfico fica, e um aviso em tom de atenção acima diz que a tela está desatualizada, com o botão do onRetry. Sem dado, é o erro de sempre.

labels.refreshing, labels.refetchError e labels.stale trocam os textos. O aviso ocupa o alto da moldura e o gráfico encolhe para caber embaixo dele: a altura continua sendo a do className.

Gradiente de área

Área chapada compete com a linha que a delimita: a cor cheia embaixo pesa tanto quanto o traço em cima, e num gráfico de duas séries a de trás some atrás da da frente.

function Receita() {
  return (
    <ChartContainer config={config} className="h-64">
      <AreaChart data={meses}>
        <ChartAreaGradient id="receita" series={['assinaturas']} />
        <Area
          dataKey="assinaturas"
          stroke="var(--color-assinaturas)"
          fill={areaGradient('receita', 'assinaturas')}
        />
      </AreaChart>
    </ChartContainer>
  )
}

O id do gradiente sai do id deste gráfico. Sem isso, dois gráficos na mesma página com o mesmo nome de série pintariam um com o gradiente do outro, porque id de SVG é global no documento.

Movimento

A moldura cuida do movimento sozinha, e nenhuma marca precisa de prop para isso. Toda Line, Bar, Area, Pie, Radar, RadialBar e Scatter que ela embrulha sai com três props vestidas:

  • animationDuration lido de --rc-duration-slow, e animationEasing lido de --rc-ease, no valor computado da própria moldura. A Recharts interpola em JavaScript e não enxerga variável de CSS; por isso a moldura lê o token depois de montar e entrega o número. O padrão da Recharts (1500 ms, ease) não aparece em lugar nenhum.
  • isAnimationActive ligado antes de a marca montar, e desligado com "reduzir movimento": na primeira vez que aparece com dados, o gráfico se desenha, e depois anda quando o dado muda.

A barra cresce da base, a linha e a área se revelam da esquerda, a rosca e o arco varrem do zero. O gráfico que chega depois do isLoading, do erro ou do vazio também entra desenhando: o esqueleto era a espera, e o desenho é o dado chegando. Depois disso, o que o movimento informa é a mudança: o filtro trocou, o mês virou, e a barra que anda do valor velho ao novo mostra quanto mudou. A duração é uma só, a de --rc-duration-slow, na entrada e na troca: a Recharts reinicia a animação quando a duração muda, e trocar o número depois da entrada faria o gráfico se desenhar duas vezes.

No servidor o gráfico não desenha. A Recharts só pinta depois de medir a caixa, então o HTML do SSR sai com a moldura, a legenda e o anúncio, e sem o SVG. A moldura lê os tokens num efeito de layout, antes de a medida chegar, e a primeira marca que monta no cliente já monta animada: não existe um quadro com o desenho pronto que depois some para crescer de novo. O Alert do erro e o EmptyState do vazio entram pelo movimento deles.

Marca com isAnimationActive={false} fica parada: a moldura só liga o que ninguém desligou. animationDuration e animationEasing escritos à mão também vencem.

useChartMotion() continua exportado e devolve o mesmo trio, para quem desenha com a Recharts fora da moldura:

const motion = useChartMotion()

<Line dataKey="entregues" stroke="var(--color-entregues)" {...motion} />

Dentro do ChartContainer ele é dispensável, e espalhá-lo não muda nada: a moldura veste a marca do mesmo jeito. Fora dela, a entrada depende de a marca montar depois do primeiro efeito, e é o que acontece com o gráfico dentro de um ResponsiveContainer, que só desenha depois de medir. Num gráfico de largura e altura fixas, a marca monta no mesmo quadro do gancho, nasce pronta e só anda na troca de dado.

As peças da Recharts que saem daqui

Area, AreaChart, Bar, BarChart, Line, LineChart, Pie, PieChart, Cell, Scatter, ScatterChart, Radar, RadarChart, RadialBar, RadialBarChart, PolarGrid, PolarAngleAxis, PolarRadiusAxis, CartesianGrid, XAxis, YAxis, ZAxis, LabelList, Rectangle, ReferenceLine e ReferenceArea.

A lista é curada, e não um export *. O Tooltip e o Legend da Recharts não saem por aqui: os nossos já embrulham os dois, e o nome colidiria com o Tooltip do catálogo.

Os eixos

ChartXAxis e ChartYAxis embrulham os da Recharts com a cor, a fonte e o respiro do tema, e com o format da casa: format="dayMonth" no eixo do tempo, format="currencyShort" no de valor. Sem eles, cada tela escreve o próprio tickFormatter e um eixo lê diferente do outro: R$ 12.400 aqui, 12400 ali, 12,4k na terceira.

A largura do ChartYAxis sai do format: ele abre espaço para o rótulo mais largo que aquele formato escreve até as centenas de milhar, negativo incluído, e por isso "R$ 280K" não perde o "R" na borda. Sem format, são 56px. Valor na casa dos milhões com format="currency", ou função própria que escreva mais que isso, pede width - ou width="auto", que mede no navegador. O width que você passa sempre vence.

Passe à dica o mesmo formato do eixo do tempo, em formatLabel: sem ele, o eixo diz "jun" e a dica diz "2026-06-01".

<ChartXAxis dataKey="mes" format="monthShort" />
<ChartTooltip content={<ChartTooltipContent config={config} formatLabel="monthShort" />} />

Quando não usar

Para a tendência que cabe dentro de um número, use Sparkline, sem eixo nem moldura, no slot chart do Stat: a moldura inteira ao lado de cada indicador enche o painel.

Os gráficos de forma própria já vêm prontos: parte de um todo é ChartDonut, número julgado por faixas é ChartGauge, etapas com conversão é ChartFunnel, grade de linha por coluna é ChartHeatmap e proporção de muitas categorias é ChartTreemap. E quando a pessoa precisa do valor exato de cada linha, e não da forma, é DataTable.

No React Native

Traduz, no caminho próprio @rivocode/ui-native/chart, com o mesmo arranjo do formulário, agora pelo peso: o react-native-svg com que ele desenha é peer obrigatório da raiz desde a 6.0, porque os ícones do pacote são do lucide-react-native, e quem monta formulário não carrega as escalas e as marcas.

O que atravessa inteiro são os quatro finais. isLoading, isError, onRetry, errorTitle, errorMessage, labels.retry, empty e data têm os mesmos nomes e o mesmo sentido, e a espera desenha as mesmas seis barras desiguais. Três diferenças de tipo, todas porque texto no nativo mora dentro de um Text: errorMessage, empty.title e empty.description são string. O empty.icon atravessa, e aceita também a função do EmptyState nativo. O botão de tentar de novo fica fora do aviso: o Alert nativo tem título e corpo, e o corpo é uma linha de texto.

O que muda é o desenho. No web a moldura embrulha um gráfico da Recharts, que mede o pai sozinho e lê a cor de cada série em var(--color-série). Aqui não há Recharts, não há contentor que meça e não há variável viva. Então a moldura mede com onLayout, resolve as cores do config e entrega as duas coisas a quem desenha, como o Form nativo entrega o submit:

<ChartContainer config={SERIES} data={meses} className="h-56">
  {({ width, height, colors }) => (
    <Svg width={width} height={height}>…</Svg>
  )}
</ChartContainer>

O colors do quadro é um mapa pela chave do config, e não um array: é o var(--color-série) do web com outro veículo, e quem desenha pede a cor de receita pelo nome, que é o que sobrevive a alguém reordenar o config. O array é o PALETTE, e ele é array dos dois lados: é a ordem de sobra, de onde sai a cor de quem não declarou color. A diferença é que aqui ele é exportado, porque sem variável viva quem desenha à mão precisa alcançá-lo.

A medida chega zerada no primeiro quadro e verdadeira no seguinte: no telefone não existe largura antes do layout. O children também aceita JSX comum, e é assim que ChartDonut e ChartRadial ganham os quatro finais sem precisar de nada da moldura.

Duas regras a mais, as duas por causa do que não existe do lado de cá. O config.color pede papel de token (chart-1 a chart-8), e não cor de CSS: a cor que a peça recebe é o valor final que vai para o desenho, e um hexadecimal escrito ali seria a única coisa da tela surda ao tema do cliente. E o label só vale na forma de função: com filho em JSX quem nomeia é a peça de dentro, e um accessible por cima dela fecharia a legenda da rosca numa parada só do leitor de tela.

O movimento vem em duas marcas, porque aqui não há Line nem Bar para a moldura vestir. ChartBar é a barra (x, y, width, height, fill, radius) e ChartLine é a linha (points em px, stroke, strokeWidth, baseline), as duas no mesmo caminho /chart. Na montagem elas entram (a barra cresce da base; a linha sobe da baseline, ou do ponto mais baixo) e, quando o valor muda, andam até o novo com a duração e a curva dos tokens (duration-slow, ease), pelo Reanimated sobre o react-native-svg: a mesma decisão do web, de que o gráfico se desenha ao aparecer e anda quando o dado muda. Com "reduzir movimento" elas nascem no lugar e saltam. A linha anda ponto a ponto quando a contagem é a mesma de antes, e troca de uma vez quando não é. Quem desenha com Rect e Path crus continua podendo, e fica parado.

API

PropTipoPadrão
configobrigatória0.4.0ChartConfigsem padrão
data0.4.0

Os pontos, para a moldura saber contar zero.

readonly unknown[]sem padrão
empty0.4.0

O que aparece quando a consulta volta sem nenhum ponto.

{ title: ReactNode; description: ReactNode; action?: ReactNode; icon?: ReactNode; illustration?: ReactNode; }sem padrão
errorIllustration

O desenho do erro de pagina ou de secao: o `ServerError` de `@rivocode/ui/illustrations`, ou o Bacalhau `pose="sad" motion="shake"` em produto da RivoCode.

ReactNodesem padrão
errorMessage0.4.0ReactNodesem padrão
errorTitle

O titulo do aviso de erro.

ReactNode"Não foi possível carregar o gráfico"
isError0.4.0booleansem padrão
isFetching

Ha uma busca correndo, inclusive a que revalida os pontos que ja estao na tela - o `isFetching` do TanStack Query.

booleansem padrão
isLoading0.4.0booleansem padrão
isRefetchError

A ultima busca falhou, mas os pontos anteriores continuam validos - o `isRefetchError` do TanStack Query.

booleansem padrão
label

O que o leitor de tela ouve no lugar do desenho.

stringsem padrão
labels

Os textos da peca, para trocar o idioma: `retry` e o botao que executa o `onRetry`, "Tentar de novo" sem ele - a mesma chave em todas as pecas que resolvem os quatro finais.

Partial<ChartContainerLabels>sem padrão
onRetry0.4.0

Sem isto, o erro nao oferece nova tentativa.

(() => void)sem padrão

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

Partes

ChartContainer se monta com estas peças. Todas vivem nesta página, porque separar cada uma num endereço obrigaria a abrir seis abas para montar uma tela.

ChartLegendContent

/chart-legend-content.md

A legenda, com o nome que o config deu a cada série. Entra no content do ChartLegend.

Sem ela a Recharts mostra a chave crua do dado, qtd_pedidos em vez de "Pedidos": nome de campo não é texto de tela.

Na pizza todas as fatias dividem o mesmo dataKey, e quem separa uma da outra é o name. A legenda olha os dois, nessa ordem.

Os itens saem na ordem das chaves do config, e não na que a Recharts entrega

  • que é alfabética. A dica segue a mesma ordem, então "Pedidos, Devolvidos" na legenda é "Pedidos, Devolvidos" na dica.

Com hidden e onToggle - o par que o useSeriesToggle devolve -, cada item vira botão que liga e desliga a série. O aria-pressed diz se a série está na tela: pressionado é visível, e solto é escondida, riscada na legenda.

PropTipo
config0.4.0ChartConfig
hidden0.4.0

As series escondidas agora.

readonly string[]
onToggle0.4.0

Chamado com a chave da serie clicada.

((key: string) => void)
payload0.4.0readonly LegendPayload[]

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

ChartTooltipContent

/chart-tooltip-content.md

A dica que segue o ponteiro, vestida com os nossos tokens. Entra no content do ChartTooltip.

Ela substitui a dica da Recharts inteira, em vez de pintar por cima: a original sai com fundo branco e borda cinza escritos em estilo embutido, e não há classe que corrija estilo embutido: no tema escuro ela vira um retângulo branco no meio do gráfico.

formatValue formata o número; use para dinheiro e porcentagem.

O rótulo do ponto

O topo da dica é o valor do eixo X daquele ponto, e ele chega cru: num gráfico de tempo, "2026-06-01". formatLabel escreve esse rótulo com o mesmo vocabulário do format do eixo - 'monthShort', 'dayMonth' ou uma função própria -, e o certo é passar o mesmo dos dois lados:

<ChartXAxis dataKey="mes" format="monthShort" />
<ChartTooltip content={<ChartTooltipContent config={config} formatLabel="monthShort" />} />

Sem formatLabel, vale o labelFormatter do ChartTooltip, como na Recharts; sem os dois, o rótulo sai como veio. O que o leitor de tela ouve ao andar pelos pontos com as setas é o texto da dica, então o anúncio sai no mesmo formato.

A ordem

As linhas da dica seguem a ordem das chaves do config, a mesma da legenda. Série que o config não conhece vai para o fim, na ordem em que chegou.

PropTipo
active0.4.0

Com `true`, a dica fica sempre à vista depois que um `activeIndex` é definido, pelo mouse ou por código.

boolean
config0.4.0ChartConfig
formatLabel

Como o rotulo do ponto e escrito no topo da dica: o mesmo vocabulario do `format` do eixo (`'monthShort'`, `'dayMonth'`...) ou uma funcao propria.

Format
formatValue0.4.0

Formata o valor.

((value: number, key: string) => ReactNode)
hideIndicator0.4.0

Esconde a bolinha de cor de cada linha.

boolean
label0.4.0string | number
labelFormatter

A função que formata o rótulo da dica.

(((label: ReactNode, payload: readonly Payload<number, string>[]) => ReactNode) & ((label: ReactNode, payload: TooltipPayload) => ReactNode))
payload0.4.0TooltipPayload

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

@rivocode/ui, 149 peças no catálogo. Esta página é gerada dos mesmos arquivos que alimentam o design system, então ela não envelhece sozinha.

Feito por RivoCode.