Date Picker
O br-date-picker é o subcomponente de calendário com grade visual de dias, meses e anos. É orquestrado automaticamente pelo componente principal <br-datetime-picker>, mas também pode ser utilizado de forma avulsa quando apenas um calendário estático for necessário.
Visão Geral
Subcomponente de calendário visual do GovBR-DS, projetado para seleção interativa de datas individuais ou intervalos.
Papel na composição
- Exibe a grade mensal navegável com suporte a seleção de dia, navegação entre meses e anos, e destaque para a data atual e intervalos.
- Implementa navegação acessível por teclado WAI-ARIA Grid (setas direcionais para dias e semanas).
Regra de uso e relacionamento
Geralmente exibido dentro da superfície suspensa coordenada pelo br-datetime-picker. Pode ser declarado isoladamente quando a interface demandar um calendário estático permanentemente embutido na página (inline calendar).
Para a documentação completa de design, consulte o Design System do GovBR.
Exemplo(s)
Propriedades
disabled
| Atributo | disabled |
|---|---|
| Descrição | Desabilita a interação do calendário quando ativo. |
| Tipo | boolean |
| Valor padrão | false |
disabledDates
| Atributo | --- |
|---|---|
| Descrição | Lista de datas indisponíveis para seleção no calendário. Recebe instâncias de Date por property binding; datas inválidas são ignoradas. |
| Exemplo de uso | |
| Tipo | Date[] |
| Valor padrão | [] |
fixedRowCount
| Atributo | fixed-row-count |
|---|---|
| Descrição | Define se o calendário deve manter um número fixo de linhas (6 semanas = 42 dias) ou variar conforme o mês. Quando true, o calendário sempre exibe 6 semanas completas.Quando false, o calendário adapta-se ao mês, exibindo apenas as semanas necessárias. |
| Tipo | boolean |
| Valor padrão | false |
locale
| Atributo | locale |
|---|---|
| Descrição | Locale usado para gerar nomes de meses e dias da semana. |
| Tipo | string |
| Valor padrão | 'pt-BR' |
rangeEnd
| Atributo | --- |
|---|---|
| Descrição | Data final selecionada quando o calendário opera no modo de intervalo. |
| Tipo | Date |
| Valor padrão | null |
rangeStart
| Atributo | --- |
|---|---|
| Descrição | Data inicial selecionada quando o calendário opera no modo de intervalo. |
| Tipo | Date |
| Valor padrão | null |
rangeValue
| Atributo | --- |
|---|---|
| Descrição | Intervalo controlado no modo range, reunindo rangeStart e rangeEnd em uma atualização.Deve conter datas válidas ou null; valores inválidos são ignorados. Passe o objeto por property binding. |
| Exemplo de uso | |
| Tipo | { start: Date; end: Date; } |
| Valor padrão | --- |
referenceDate
| Atributo | --- |
|---|---|
| Descrição | Data usada como base visual para o mês atualmente exibido, sem alterar a seleção. Recebe uma instância de Date por property binding; valores inválidos usam a data atual. |
| Exemplo de uso | |
| Tipo | Date |
| Valor padrão | new Date() |
selectionMode
| Atributo | selection-mode |
|---|---|
| Descrição | Define se a seleção ocorre por data única ou por intervalo. Valores inválidos usam single. |
| Tipo | "range" | "single" |
| Valor padrão | 'single' |
value
| Atributo | --- |
|---|---|
| Descrição | Data efetivamente selecionada, ou null quando não há seleção; é diferente de referenceDate, que controla apenas o mês visível.Recebe uma instância de Date por property binding; datas inválidas usam null. |
| Exemplo de uso | |
| Tipo | Date |
| Valor padrão | null |
weekStartsOn
| Atributo | week-starts-on |
|---|---|
| Descrição | Define o índice do dia em que a semana começa na interface do calendário. |
| Tipo | 0 | 1 | 2 | 3 | 4 | 5 | 6 |
| Valor padrão | 0 |
Eventos
| Evento | Descrição | Depreciação | Propagação |
|---|---|---|---|
dateStateChange | Evento emitido quando a data de referência ou a seleção mudam. | --- | true |
CSS Shadow Parts
| Nome | Descrição |
|---|---|
"calendar" | Grade geral do calendário. |
"container" | Parte para o container base do calendário. |
"day" | Célula individual do dia no calendário. |
"grid" | Grade de dias do mês. |
"header" | Cabeçalho do calendário (contendo navegação e seleção de mês/ano). |
"month-select" | Elemento de seleção do mês. |
"weekday" | Rótulo individual do dia da semana. |
"weekdays" | Container para os rótulos dos dias da semana. |
"year-input" | Elemento de entrada do ano. |
Locales adicionais
O br-date-picker inclui apenas o locale pt-BR no bundle padrão. Para usar
outro locale, importe-o diretamente do date-fns e registre-o uma vez antes de
renderizar o componente:
import { enUS } from 'date-fns/locale/en-US';
import { registerDatePickerLocale } from '@govbr-ds/webcomponents';
registerDatePickerLocale('en-US', enUS);
Depois do registro, use o código normalmente:
<br-date-picker locale="en-US"></br-date-picker>
O código usado no registro deve corresponder ao valor informado na propriedade
locale. O pt-BR permanece disponível sem registro. Se um locale não tiver
sido registrado, o componente usa pt-BR como fallback.
O registro é global para os date pickers da página. Faça-o uma vez no bootstrap da aplicação e importe apenas os locales que realmente serão utilizados.
Dependências
Componente pai
Usado por
Depende de
Gráfico
Migração para <br-date-picker>
O br-date-picker não existia na linha 1.x. Ele foi criado na 2.x como o calendário usado por br-datetime-picker.
Na maioria das aplicações, use o componente pai:
<br-datetime-picker mode="date" name="data" placeholder="Selecione a data"></br-datetime-picker>
Use br-date-picker diretamente apenas quando a tela precisar de um calendário sempre visível. Nesse caso:
valuerecebe a data selecionada;referenceDatecontrola o mês exibido;disabledDatesinforma as datas indisponíveis; limitesminemaxpertencem aobr-datetime-picker;selectionMode="range"habilita intervalo e expõerangeValue;dateStateChangeinforma mudanças de navegação e seleção ao componente que coordena o calendário.
Valores do tipo Date devem ser atribuídos como propriedades JavaScript, e não como atributos HTML serializados.
