MonthPicker
Mês da fatura
Com limites do ano
Vazio
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
| Prop | Tipo | Padrão |
|---|---|---|
classNamesClasse por parte: `panel` (o painel), `grid` (a grade dos meses) e `month` (cada mes). | Partial<Record<"grid" | "month" | "panel", string>> | sem padrão |
defaultValueA competencia inicial, quando o componente controla o proprio estado. | string | null | null |
labelsOs 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 |
maxA ultima competencia aceita, inclusive, em `aaaa-mm`. | string | sem padrão |
minA primeira competencia aceita, inclusive, em `aaaa-mm`. | string | sem padrão |
onValueChangeChamado 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 |
renderTroca 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 |
sizeTamanho do campo, o mesmo vocabulario do Input. | "lg""md""sm" | sem padrão |
valueA competencia escolhida, em `aaaa-mm`. | string | null | sem padrão |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.