# DateTimePicker

Data e hora num valor só: agendamento, vencimento com hora, prazo de SLA.

São dois campos lado a lado, o do `DatePicker` (`dd/mm/aaaa`, com o
calendário) e o do `TimeField` (`hh:mm`, com as setas), e um valor único em
`aaaa-mm-ddThh:mm`, na hora local e sem fuso. O valor só sai quando as duas
metades estão inteiras; a metade escolhida fica no campo dela e espera a
outra. Apagar a data, ou a hora, responde `null`, e a outra metade continua lá
para a próxima escolha. No celular os dois campos se empilham, porque a hora
ganha os botões de mais e de menos do `TimeField` e não cabe ao lado da data.

```tsx
const [visita, setVisita] = useState<string | null>(null)

<DateTimePicker aria-label="Visita técnica" value={visita} onValueChange={setVisita} />
```

`defaultTime` preenche a hora sozinha quando a data é escolhida com a hora
vazia: `defaultTime="18:00"` é o vencimento no fim do dia, e um clique no
calendário já fecha o valor. `min` e `max` limitam os dias, em `aaaa-mm-dd`; a
hora não é recortada. `step` é o passo das setas da hora.

O componente é um grupo (`role="group"`), e cada campo se apresenta ao leitor
de tela como "Data" e "Hora" (`labels` troca). Dentro de um `Field`, o
`FieldLabel` nomeia o grupo e entra no nome das duas partes: quem navega campo
a campo ouve "Vencimento Data" e "Vencimento Hora", e não dois campos soltos
com o mesmo nome. O clique no rótulo leva à data. Fora do `Field`, dê o nome do
grupo com `aria-label`, ou com `aria-labelledby`, que também entra no nome das
partes; ou ponha a peça num `Fieldset` com `FieldsetLegend`, que diz o nome uma
vez para os dois. Com `name`, um campo escondido leva o valor inteiro no envio,
e só ele: o texto pontuado da data não vai junto. No `FormField`, entra pelo
`forValue`.

```tsx
<Field name="dueAt">
  <FieldLabel>Vencimento</FieldLabel>
  <DateTimePicker defaultTime="18:00" value={due} onValueChange={setDue} />
</Field>
```

O texto vira `Date` com `new Date(valor)`, que lê na hora local. Para mandar ao
servidor com fuso, converta na borda, e não no campo.

Com `readOnly`, os dois campos mostram o valor com a borda tracejada e nem o
calendário nem o passo da hora mudam nada. Dentro de `<Field disabled>`, os
dois ficam desligados.

## Quando não usar

Quando só o dia importa, use `DatePicker`: hora que ninguém escolheu vira
`00:00` no banco e aparece como meia-noite no relatório. Hora sozinha, sem dia
(abertura da loja, janela de entrega), é `TimeField`. E dois horários do mesmo
dia (início e fim) são dois `TimeField`, e não dois `DateTimePicker`.

## No React Native

Traduz com o mesmo valor único, `aaaa-mm-ddThh:mm`, e a mesma regra: só sai com as duas metades, `null` quando uma some, e `defaultTime` fecha o valor na escolha da data. Os dois campos de digitar do web viram dois gatilhos de folha, o do `DatePicker` (o mês) e o do `TimePicker` (as duas colunas), porque no celular escolher é mais curto que digitar. Cada gatilho anuncia o `label` com a parte: "Vencimento, data" e "Vencimento, hora". Dentro de um `Field`, sem `label`, vale o rótulo do `Field`, como o `FieldLabel` faz no web; fora dele, o `label` é o único nome que os gatilhos têm.

**`min` e `max` aceitam a hora, e aqui ela recorta.** Com `aaaa-mm-ddThh:mm`, no dia de cada ponta a folha da hora começa ou termina nela, e nos outros dias a hora é livre; só com o dia, a hora não é recortada, como no web. A janela de todo dia é `minTime` e `maxTime`, em `hh:mm`, com os nomes e a conta do web: no dia de uma ponta vale a hora mais apertada entre as duas, e nos outros dias vale só a janela.

## Importação

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

## Exemplos

### Agendamento

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

export function Schedule() {
  const [visit, setVisit] = useState<string | null>('2026-10-20T09:30')
  return (
    <DateTimePicker
      aria-label="Visita técnica"
      className="w-full max-w-80"
      value={visit}
      onValueChange={setVisit}
    />
  )
}
```

### Dentro de um Field

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

export function InsideField() {
  const [due, setDue] = useState<string | null>('2026-10-30T18:00')
  return (
    <Field className="w-full max-w-80">
      <FieldLabel>Vencimento da proposta</FieldLabel>
      <DateTimePicker defaultTime="18:00" value={due} onValueChange={setDue} />
    </Field>
  )
}
```

### Vencimento no fim do dia

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

export function DueAtEndOfDay() {
  const [due, setDue] = useState<string | null>(null)
  return (
    <Fieldset className="w-full max-w-80">
      <FieldsetLegend>Prazo de resposta</FieldsetLegend>
      <DateTimePicker
        defaultTime="18:00"
        value={due}
        onValueChange={setDue}
      />
    </Fieldset>
  )
}
```

## Props

| Prop | Tipo | Obrigatória | Padrão | Desde | O que faz |
| --- | --- | --- | --- | --- | --- |
| `classNames` | `Partial<Record<"date" \| "time", string>>` |  |  | - | Classe por parte: `date` (o campo da data) e `time` (o campo da hora). |
| `defaultTime` | `string` |  |  | - | A hora que entra sozinha quando a data e escolhida com a hora vazia, em `hh:mm`: "18:00" para vencimento no fim do dia. |
| `defaultValue` | `string \| null` |  | `null` | - | O valor inicial, quando o componente controla o proprio estado. |
| `disabled` | `boolean` |  |  | - |  |
| `labels` | `Partial<DateTimePickerLabels>` |  |  | - | Os textos da peca, para trocar o idioma: `date` e `time` sao os nomes que o leitor de tela ouve em cada campo. |
| `max` | `string` |  |  | - | O ultimo momento aceito, inclusive: `aaaa-mm-dd` limita so o dia, e `aaaa-mm-ddThh:mm` limita tambem a hora no proprio dia. |
| `maxTime` | `string` |  |  | - | A ultima hora aceita em qualquer dia, em `hh:mm`. |
| `min` | `string` |  |  | - | O primeiro momento aceito, inclusive: `aaaa-mm-dd` limita so o dia, e `aaaa-mm-ddThh:mm` limita tambem a hora no proprio dia - nos outros dias a hora fica livre. |
| `minTime` | `string` |  |  | - | A primeira hora aceita em qualquer dia, em `hh:mm`: o expediente que abre as 08:00. |
| `name` | `string` |  |  | - | O nome do campo escondido que leva o valor inteiro ao formulario. |
| `onValueChange` | `((value: string \| null) => void)` |  |  | - | Chamado com o valor inteiro quando data e hora estao completas, e com `null` quando uma das duas esvazia. |
| `readOnly` | `boolean` |  |  | - | Mostra a data e a hora sem deixar mudar: os dois campos ficam com a borda tracejada, e o calendario e o passo da hora nao abrem nem andam. |
| `size` | `"lg" \| "md" \| "sm"` |  |  | - | Tamanho dos dois campos, o mesmo vocabulario do Input. |
| `step` | `number` |  |  | - | De quantos minutos as setas da hora andam. |
| `value` | `string \| null` |  |  | - | A data e a hora escolhidas, num valor so, em `aaaa-mm-ddThh:mm` e na hora local, sem fuso. |

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)
