ChartContainer
Linha
Vazio, com saída
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
Não foi possível carregar os pedidos
A consulta expirou. Tente de novo em alguns minutos.
Área com gradiente
Barra
Barra empilhada
Barra deitada, com rótulo
Radar
Dispersão
Vazio sem empty: o aviso curto
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
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:
animationDurationlido de--rc-duration-slow, eanimationEasinglido 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.isAnimationActiveligado 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
| Prop | Tipo | Padrão |
|---|---|---|
configobrigatória0.4.0 | ChartConfig | sem padrão |
data0.4.0Os pontos, para a moldura saber contar zero. | readonly unknown[] | sem padrão |
empty0.4.0O que aparece quando a consulta volta sem nenhum ponto. | { title: ReactNode; description: ReactNode; action?: ReactNode; icon?: ReactNode; illustration?: ReactNode; } | sem padrão |
errorIllustrationO 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. | ReactNode | sem padrão |
errorMessage0.4.0 | ReactNode | sem padrão |
errorTitleO titulo do aviso de erro. | ReactNode | "Não foi possível carregar o gráfico" |
isError0.4.0 | boolean | sem padrão |
isFetchingHa uma busca correndo, inclusive a que revalida os pontos que ja estao na tela - o `isFetching` do TanStack Query. | boolean | sem padrão |
isLoading0.4.0 | boolean | sem padrão |
isRefetchErrorA ultima busca falhou, mas os pontos anteriores continuam validos - o `isRefetchError` do TanStack Query. | boolean | sem padrão |
labelO que o leitor de tela ouve no lugar do desenho. | string | sem padrão |
labelsOs 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.0Sem 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.mdA 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.
| Prop | Tipo |
|---|---|
config0.4.0 | ChartConfig |
hidden0.4.0As series escondidas agora. | readonly string[] |
onToggle0.4.0Chamado com a chave da serie clicada. | ((key: string) => void) |
payload0.4.0 | readonly LegendPayload[] |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.
ChartTooltipContent
/chart-tooltip-content.mdA 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.
| Prop | Tipo |
|---|---|
active0.4.0Com `true`, a dica fica sempre à vista depois que um `activeIndex` é definido, pelo mouse ou por código. | boolean |
config0.4.0 | ChartConfig |
formatLabelComo 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.0Formata o valor. | ((value: number, key: string) => ReactNode) |
hideIndicator0.4.0Esconde a bolinha de cor de cada linha. | boolean |
label0.4.0 | string | number |
labelFormatterA função que formata o rótulo da dica. | (((label: ReactNode, payload: readonly Payload<number, string>[]) => ReactNode) & ((label: ReactNode, payload: TooltipPayload) => ReactNode)) |
payload0.4.0 | TooltipPayload |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.