# MonthPicker

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.

```tsx
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.

## Importação

```tsx
import { MonthPicker } from '@rivocode/ui'
```

## Exemplos

### Mês da fatura

```tsx
import { Field, FieldLabel, MonthPicker } from '@rivocode/ui'
import { useState } from 'react'

export function Competence() {
  const [competence, setCompetence] = useState<string | null>('2026-09')
  return (
    <Field className="w-56">
      <FieldLabel>Mês da fatura</FieldLabel>
      <MonthPicker value={competence} onValueChange={setCompetence} />
    </Field>
  )
}
```

### Com limites do ano

```tsx
import { Field, FieldLabel, MonthPicker } from '@rivocode/ui'
import { useState } from 'react'

export function WithBounds() {
  return (
    <Field className="w-56">
      <FieldLabel>Mês do relatório</FieldLabel>
      <MonthPicker defaultValue={null} min="2026-01" max="2026-12" />
    </Field>
  )
}
```

### Vazio

```tsx
import { Field, FieldLabel, MonthPicker } from '@rivocode/ui'
import { useState } from 'react'

export function Empty() {
  return <MonthPicker aria-label="Mês de referência" className="w-56" />
}
```

## Props

| Prop | Tipo | Obrigatória | Padrão | Desde | O que faz |
| --- | --- | --- | --- | --- | --- |
| `classNames` | `Partial<Record<"grid" \| "month" \| "panel", string>>` |  |  | - | Classe por parte: `panel` (o painel), `grid` (a grade dos meses) e `month` (cada mes). |
| `defaultValue` | `string \| null` |  | `null` | - | A competencia inicial, quando o componente controla o proprio estado. |
| `labels` | `Partial<MonthPickerLabels>` |  |  | - | 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. |
| `max` | `string` |  |  | - | A ultima competencia aceita, inclusive, em `aaaa-mm`. |
| `min` | `string` |  |  | - | A primeira competencia aceita, inclusive, em `aaaa-mm`. |
| `onValueChange` | `((value: string \| null) => void)` |  |  | - | Chamado com a competencia inteira em `aaaa-mm`, pela digitacao ou pelo painel, e com `null` quando o campo esvazia. |
| `render` | `ComponentRenderFn<HTMLProps, FieldControlState> \| ReactElement<unknown, string \| JSXElementConstructor<any>>` |  |  | - | Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente. |
| `size` | `"lg" \| "md" \| "sm"` |  |  | - | Tamanho do campo, o mesmo vocabulario do Input. |
| `value` | `string \| null` |  |  | - | A competencia escolhida, em `aaaa-mm`. |

Além dessas: repassa `className`, `style`, `id` e os demais atributos do elemento raiz.

## Ver também

- [AudioRecorder](/componentes/audio-recorder.md)
- [Autocomplete](/componentes/autocomplete.md)
- [Calendar](/componentes/calendar.md)
- [Checkbox](/componentes/checkbox.md)
- [CheckboxCard](/componentes/checkbox-card.md)
- [CheckboxGroup](/componentes/checkbox-group.md)
- [Convenções da biblioteca](/convencoes.md): Provider, tokens e as regras que valem para toda peça
- [Índice completo](/llms.txt)
