Date Picker

Componente estável e recomendada para novos projetos.

Anatomia, uso, comportamento visual e recomendações conceituais são mantidos pelo Padrão Digital de Governo. Esta página documenta a implementação Web Components e sua API executável.

Subcomponente Modular

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

O br-date-picker é o subcomponente de calendário do br-datetime-picker, responsável pela seleção visual de uma data ou de um intervalo.

Papel na composição

Exibe a grade mensal, a navegação entre meses e anos e os estados de seleção e bloqueio dos dias. referenceDate determina o período exibido, enquanto value e os limites do intervalo representam a seleção.

Regra de uso e relacionamento

O br-datetime-picker instancia e configura este calendário internamente nos modos date e datetime, recebendo suas alterações pelo evento dateStateChange. Não declare o calendário em um slot do pai.

Use diretamente quando precisar de um calendário embutido e permanentemente visível. Nesse caso, a aplicação deve coordenar valores e eventos e implementar a integração com formulários e a validação do fluxo completo. O calendário isolado não fornece o campo textual, o seletor de horários nem a associação ao formulário do orquestrador.

Para a documentação completa de design, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o Design System do GovBR.

Exemplo(s)

Propriedades

disabled

Atributo	disabled
Descrição	Desabilita a interação do calendário quando true.
Tipo	boolean
Valor padrão	false

disabledDates

Atributo	---
Descrição	Lista de datas indisponíveis para seleção no calendário.
Tipo	Date[]
Valor padrão	[]

fixedRowCount

Atributo	fixed-row-count
Descrição	Se true, o calendário sempre exibe 6 semanas (42 dias); caso contrário, adapta-se ao mês.
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. Quando definido, mantém rangeStart e rangeEnd sincronizados.
Tipo	{ start: Date; end: Date; }
Valor padrão	---

referenceDate

Atributo	---
Descrição	Data usada como base visual para o mês atualmente exibido.
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.
Tipo	"range" | "single"
Valor padrão	'single'

value

Atributo	---
Descrição	Data atualmente selecionada pelo usuário, ou null quando não há seleção.
Tipo	Date
Valor padrão	null

weekStartsOn

Atributo	week-starts-on
Descriçã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	Emite o estado consolidado do componente quando há mudança de referência/seleção. Payload (DatetimePickerDateState):	---	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

• br-datetime-picker

Usado por

• br-datetime-picker

Depende de

• br-button
• br-icon

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:

• value recebe a data selecionada;
• referenceDate controla o mês exibido;
• disabledDates informa as datas indisponíveis; limites min e max pertencem ao br-datetime-picker;
• selectionMode="range" habilita intervalo e expõe rangeValue;
• dateStateChange informa 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.