Pular para o conteúdo
Formulário

MonthPicker

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

Mês da fatura

Com limites do ano

Vazio

Importar
import { MonthPicker } from '@rivocode/ui'

Quando usar

Mês e ano, sem dia. É o campo da fatura da assinatura, do relatório mensal, da folha de pagamento e do fechamento do caixa.

O valor é aaaa-mm ("2026-09"), que ordena como texto e vai direto para a API, e null é o campo vazio. Na tela, o campo mostra e aceita mm/aaaa, e nasce com esse formato no texto de espera. Digitar vale como no DatePicker: só o mês inteiro sai pelo onValueChange, e a pela metade, o mês que não existe (13/2026) ou fora dos limites ficam no campo e ganham a mensagem ao sair dele, sem apagar o que a pessoa escreveu.

O botão ao lado abre o ano com os doze meses. As setas trocam o ano, o mês escolhido fica marcado, o mês de hoje aparece em destaque, e um clique escolhe e fecha. No celular o painel vira folha de baixo, como o dos calendários.

const [month, setMonth] = useState<string | null>(null)

<Field>
  <FieldLabel>Mês do relatório</FieldLabel>
  <MonthPicker value={month} onValueChange={setMonth} min="2026-01" max="2026-12" />
</Field>

min e max são inclusivos, em aaaa-mm: desligam os meses de fora no painel, param as setas no ano do limite e recusam o que se digita fora deles. Com name, um campo escondido leva aaaa-mm no envio do formulário. No FormField, entra pelo forValue, com z.string().nullable() no schema.

Dentro de <Field>, a mensagem do mês que não vale vai para o FieldError, e o campo acende ao sair dele mesmo sem Form em volta, como no DatePicker. Com readOnly, ou dentro de <Field disabled>, o botão do ano fica desligado.

Quando não usar

Quando o dia importa (vencimento, consulta, entrega), use DatePicker: forçar o dia 1 numa data de verdade é um dado errado que parece certo. E período de vários meses é DateRangePicker, que tem atalho de "Mês passado" e "Este mês"; o mês daqui é um só, e não um intervalo.

No React Native

Traduz com o mesmo valor, aaaa-mm, e o mesmo painel: a folha de baixo mostra o ano, as setas que o trocam e os doze meses em três colunas, com o escolhido no acento e o de hoje em destaque. Um toque escolhe e fecha. Não há digitação: no celular a competência se escolhe em dois toques, e o teclado numérico cobriria a folha. min e max desligam os meses de fora e param as setas no ano do limite.

API

PropTipoPadrão
classNames

Classe por parte: `panel` (o painel), `grid` (a grade dos meses) e `month` (cada mes).

Partial<Record<"grid" | "month" | "panel", string>>sem padrão
defaultValue

A competencia inicial, quando o componente controla o proprio estado.

string | nullnull
labels

Os textos da peca, para trocar o idioma: `open` e o nome do botao do painel, `title` o titulo do painel, `previousYear` e `nextYear` as setas do ano.

Partial<MonthPickerLabels>sem padrão
max

A ultima competencia aceita, inclusive, em `aaaa-mm`.

stringsem padrão
min

A primeira competencia aceita, inclusive, em `aaaa-mm`.

stringsem padrão
onValueChange

Chamado com a competencia inteira em `aaaa-mm`, pela digitacao ou pelo painel, e com `null` quando o campo esvazia.

((value: string | null) => void)sem padrão
render

Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente.

ComponentRenderFn<HTMLProps, FieldControlState> | ReactElement<unknown, string | JSXElementConstructor<any>>sem padrão
size

Tamanho do campo, o mesmo vocabulario do Input.

"lg""md""sm"sem padrão
value

A competencia escolhida, em `aaaa-mm`.

string | nullsem padrão

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.