Gå til hovedinnhold
KOMPONENTER

Datepicker

npmv9.3.0

DatePicker, DateField, Calendar og NativeDatePicker er komponenter for å velge datoer.

npm install @entur/datepicker
@import '@entur/datepicker/dist/styles.css';
() => {
const [date, setDate] = React.useState(now('Europe/Oslo'))
return (
<DatePicker
label="Dato"
selectedDate={date}
onChange={date => setDate(date)}
locale="nb-NO"
/>
)
}

Bruk

DatePicker hjelper brukeren å velge en dato – og evt. et tidspunkt. Den bruker pakken @internationalized/date i bakgrunnen til håndtering av dato-objektet, inkludert tidssoner – dette er tilsvarende i TimePicker. DatePicker støtter også ulike locals og språk. DatePicker bygger på react-aria og støtter det meste av funksjonalitet du finner der, les mer her.

OBS: hjelpefunksjoner fra @internationalized/date (typ. now() og isWeekend()) er ikke inkludert i @entur/datepicker, legg til @internationalized/date i repo ditt for å bruke dem.

Språk og locale

Språk og locals er støttet gjennom to metoder. All automatisk tilpassing av språk skjer gjennom prop-en locale eller react-aria sin <I18nProvider />. locale støtter strenger på BCP 47-formatet, eks. nb-NO for norsk. Her finner du en liste over BCP 47-koder. Som default velges den locale-en som er satt på brukeren maskin.

Ledeteksten (label), og navigationDescription* må sende inn manuell oversettelse for. For navigationDescription vil en norsk og engelsk verdi følge med automatisk, men andre språk må legges inn selv.

*navigationDescription er en prop som forteller brukeren hvordan de kan navigere i kalenderen med tastaturet.

DatePicker tilpasset USA

() => {
const [date, setDate] = React.useState(now('Europe/Oslo'))
return (
<DatePicker
label="Date"
selectedDate={date}
onChange={date => setDate(date)}
locale="en-US"
/>
)
}

Tidssoner

TimePicker støtter tidssonehåndtering for å sikre lik opplevelse på tvers av tidssoner. Dette håndteres ved @internationalized/date sitt ZonedDateTime-objekt. Under er et eksempel på hvordan du lager state for nåværende dato og tidspunkt i norsk tidssone, og for et spesifikt tidspunkt i Los Angeles sin tidssone:

// nåværende tidspunkt i norsk tidssone
const [date, setDate] = React.useState(now('Europe/Oslo'));
// spesifikt tidspunkt i Los Angeles sin tidssone
const [date2, setDate2] = React.useState(parseZonedDateTime('2022-11-07T00:45[America/Los_Angeles]'));

Les mer om hvordan opprette og bruke tidssonefunksjonalitet her.

Datovalidering

Hvis du ønsker å begrense tilgjengelige datoer for brukeren, samt gi en tilbakemelding når en dato utenfor dette intervallet er valgt, kan du benytte minDate- og maxDate-props-ene eller isDateUnavailable()-valideringsfunksjonen. minDate og maxDate tar inn et CalendarDate-objekt. isDateUnavailable() skal ta inn en DateValue og returnerer en boolean for om datoen er gyldig.

Validering med minDate og maxDate

Følgende eksempel godtar datoer fra og med i dag til og med en måned frem:

() => {
const [date, setDate] = React.useState(
today('Europe/Oslo').add({ months: 2 }),
)
return (
<DatePicker
label="Velg dato"
selectedDate={date}
onChange={setDate}
locale="nb-NO"
minDate={today('Europe/Oslo')}
maxDate={today('Europe/Oslo').add({ months: 1 })}
validationFeedback="Valgt dato er for langt frem i tid"
/>
)
}

Validering med isDateUnavailable

Følgende eksempel godtar datoer som ikke er en helg.

() => {
const [date, setDate] = React.useState(now('Europe/Oslo'))
return (
<DatePicker
label="Velg dato"
selectedDate={date}
onChange={setDate}
locale="nb-NO"
isDateUnavailable={date => isWeekend(date, 'nb-NO')}
validationFeedback="Valgt dato kan ikke være en helgedag"
/>
)
}

Bruke JS Date i stedet for @internationalized/date

Hvis du ikke har mulighet til å bruke @internationalized/date, kan du bruke konverteringsfunksjonene: nativeDateToDateValue og timeOrDateValueToNativeDate. Disse konverterer mellom @internationalized/date sine tre dato-typer: ZonedDateTime, CalendarDateTime og CalendarDate (DateValue er en samling av disse tre typene) og Javascript sin Date. Se API under, nærmere beskrivelse finnes i JSDocs for funksjonene:

nativeDateToDateValue: (date: Date | null, noTimeOnlyDate?: boolean, timeZone?: string | undefined, offset?: number | undefined) => CalendarDateTime | ZonedDateTime | CalendarDate | null;
timeOrDateValueToNativeDate: (value: TimeValue | DateValue | null, timeZoneForCalendarDateTime?: string | undefined) => Date | null;

Eksempel på bruk av JS-date med DatePicker

Bruk sammen med TimePicker

Du kan velge et tidspunkt sammen med datoen på to ulike måter, enten inline med showTime-prop-en eller ved å bruke en TimePicker i kombinasjon med DatePicker-en.

Inline

() => {
const [date, setDate] = React.useState(now('Europe/Oslo'))
return (
<DatePicker
label="Velg dato og tid"
selectedDate={date}
onChange={setDate}
locale="nb-NO"
showTime
/>
)
}

Kombinasjon med TimePicker

I løsninger ut mot vanlige sluttbrukere er en separat dato- og tid-velger foretrukket.

() => {
const [dateTime, setDateTime] = React.useState(null)
return (
<div style={{ display: 'flex', gap: '1rem' }}>
<DatePicker
label="Dato"
selectedDate={dateTime}
onChange={setDateTime}
locale="nb-NO"
// 'forcedReturnType' er nødvendig når
// initiell state er 'null'
forcedReturnType="ZonedDateTime"
/>
<TimePicker
label="Tid"
selectedTime={dateTime}
onChange={setDateTime}
locale="nb-NO"
/>
</div>
)
}
'Invalid granularity for …' feilmelding

Hvis DatePicker initialiseres med null som selectedDate vil den som standard returnere en CalendarDate uten tidspunkt. For å fungere sammen med en TimePicker må man da tvinge den til å returnere et objekt med tid også. Dette kan du gjøre med prop-en forcedReturnType. Send inn enten ZonedDateTime eller CalendarDateTime avhengig av om du ønsker å sette en tidssoner eller ikke.

Bruk på mobile enheter

DatePicker fungerer også på mobile enheter. For å gjøre valg enklere for brukere med berøringskjermer benyttes en modal i stedet for en popover når skjermen er smalere enn 1000px. På denne måten vil alltid hele datovelgeren vises når man åpner den. Dette er mulig å skru av ved å bruke prop-en disableModal.

Ønsker man en OS-spesifikk opplevelse av DatePicker-en, kan man benytte seg av NativeDatePicker. Denne har noe styling for å gi den et Entur-preg, men vil bruke OS-et sin styling og interaksjonsmetode når man interagerer med den.

() => {
return (
<NativeDatePicker
label="Fødselsdato"
style={{ width: '15rem' }}
value="1997-07-10"
/>
)
}

Kun kalender

Hvis du ønsker å kun vise en inline kalender til brukeren kan du benytte <Calendar />-komponenten. Denne fungerer med samme type datoobjekter som <DatePicker /> og støtter mange av de samme props-ene.

Styling av datoer i kalenderen

Både DatePicker og Calendar har støtte for prop-en classNameForDate. classNameForDate skal være en funksjon som tar inn en dato og returnerer en streng med klassenavnet som skal legges til for dato-ruten.

Hvis stylingen som legges til er meningsbærende bør du også bruke ariaLabelForDate til å beskrive stylingens mening for skjermlesere o.l.

Vise ukenummer

Hvis du trenger å vise ukenummer i kalenderen kan du benytte prop-en showWeekNumbers. Du kan endre overskriften til ukenummerkolonnen ved å bruke prop-en weekNumberHeading.

Kun inputfelt

Hvis du ønsker å kun vise et inputfelt uten mulighet for en kalender-popover kan du benytte <DateField />-komponenten. Denne fungerer med samme type datoobjekter som <DatePicker /> og støtter mange av de samme props-ene.

Universell utforming

DatePicker bruker react-aria i bakgrunnen.Denne pakken sørger for gjennomgående støtte for universell utforming. Hvert datosegment er tilgjengelig med tastaturet og alle interagerbare elementer, både i inputfeltet og i kalenderen, har aria-beskrivelser.

Hvordan oppfylle UU-krav

Hvis du endrer locale (dvs. språk) til noe annet enn norsk og engelsk må du sende inn verdier på riktig språk til navigationDescription-prop-en.

Komponenter

<DatePicker />

import { DatePicker } from '@entur/datepicker';
NavnTypeDefault-verdiBeskrivelse
selectedDateDateValue | null

Den valgte datoen. Dato i ‘@internationalized/date’-pakkens format

onChange(value: MappedDateValue<DateType> | null) => void

Kalles når tiden endres. Dato i ‘@internationalized/date’-pakkens format

labelstring

Ledetekst for inputfeltet til DatePicker

locale?string Brukerenhetens selvvalgte locale

BCP47-språkkoden til locale-en du ønsker å bruke.

showTimeZone?boolean false

Viser den gjeldende tidssonen hvis en er valgt (krever at tid også vises)

showTime?boolean

Viser tidspunkt i tillegg til dato. OBS: selectedDate må være av typen CalendarDateTime eller ZonedDateTime

minDate?DateValue

Tidligste gyldige datovalg. Eks: today(getLocalTimeZone()) == i dag i lokal tidssone.

OBS: Hvis du bruker dato med tid vil tidspunktet også tas hensyn til. Gyldig fra og med den tiden som legges inn som minDate. Dato uten tid vil være gyldig hele minDate-dagen

maxDate?DateValue

Seneste gyldige datovalg. Eks: today(getLocalTimeZone()).add({days: 1}) == i morgen i lokal tidssone

OBS: Hvis du bruker dato med tid vil tidspunktet også tas hensyn til. Gyldig til og med den tiden som legges inn som maxDate. Dato uten tid vil være gyldig hele maxDate-dagen

isDateUnavailable?(((date: DateValue) => boolean) & ((date: DateValue) => boolean))

Funksjon som tar inn en dato og sier om den er utilgjengelig. Eks. (date) => isWeekend(date, ‘no-NO’) == helgedager er ikke tilgjengelig Callback that is called for each date of the calendar. If it returns true, then the date is unavailable.

feedback?string

Varselmelding, som vil komme under DatePicker sitt inputfelt

variant?VariantType

Valideringsvariant

validationFeedback?string "Ugyldig dato"

Varselmelding som forteller om ugyldig dato

validationVariant?VariantType "error"

Valideringsvariant for melding om ugyldig dato

disabled?boolean
showWeekNumbers?boolean false

Slå på visning av ukenummere i kalenderen. Overskriften for ukenummer-kolonnen kan endres med prop-en ‘weekNumberHeader’

weekNumberHeader?string '#'

Overskrift som vises for ukenummer-kolonnen. Vises kun hvis ‘showWeekNumbers’ er true.

disableModal?boolean false

Hvis true vil kalenderen alltid vises i en popover når den åpnes

modalTreshold?number 1000

Maxbredden til viewport-en for at modal skal vises

labelTooltip?ReactNode
navigationDescription?string 'Bruk piltastene til å navigere mellom datoer'

Skjermlesertest som forklarer navigasjon i kalenderen. Oversettes automatisk for engelsk locale, men ikke andre språk.

forcedReturnType?"CalendarDate" | "CalendarDateTime" | "ZonedDateTime" undefined

Tvinger typen på onChange til den gitte typen. Dette er nyttig når utgangsverdien din er ‘null’, men du ønsker at DatePicker alltid skal returnere f.eks ZonedDateTime.

Som standard returnerer onChange DateValue basert på selectedDate, eller CalendarDate hvis selectedDate er ‘null’.

classNameForDate?((date: CalendarDate) => string) undefined

Brukes for å legge til klassenavn på spesifikke datoer i kalenderen. Tar inn en dato og skal returnere klassenavnet som skal legges til den datoen. @example (date) => isWeekend(date, ‘no-NO’) ? ‘weekend’ : ‘’

OBS: hvis stylingen er meningsbærende bør du bruke ariaLabelForDate i tillegg for å beskrive meningen til skjermlesere o.l.

ariaLabelForDate?((date: CalendarDate) => string) undefined

Legger til teksten som returneres på datoen i kalenderen sin aria-label. Bør brukes sammen med classNameForDate hvis styling-endringene gjort der er meningsbærende. @example (date) => isWeekend(date, ‘no-NO’) ? ‘helgedag’ : ‘’

className?string

Ekstra klassenavn

style?CSSProperties

<DateField />

import { DateField } from '@entur/datepicker';

Denne komponenten har ingen props

<Calendar />

import { Calendar } from '@entur/datepicker';
NavnTypeDefault-verdiBeskrivelse
selectedDateDateValue | null
onChange(SelectedDate: MappedDateValue<DateType> | null) => void | Dispatch<SetStateAction<DateType | null>>
navigationDescription?string
style?CSSProperties
className?string

Ekstra klassenavn

onSelectedCellClick?(() => void)
minDate?DateValue

Tidligste gyldige datovalg. Eks: today(getLocalTimeZone()) == i dag i lokal tidssone.

OBS: Hvis du bruker dato med tid vil tidspunktet også tas hensyn til. Gyldig fra og med den tiden som legges inn som minDate. Dato uten tid vil være gyldig hele minDate-dagen

maxDate?DateValue

Seneste gyldige datovalg. Eks: today(getLocalTimeZone()).add({days: 1}) == i morgen i lokal tidssone

OBS: Hvis du bruker dato med tid vil tidspunktet også tas hensyn til. Gyldig til og med den tiden som legges inn som maxDate. Dato uten tid vil være gyldig hele maxDate-dagen

showWeekNumbers?boolean false

Slå på visning av ukenummere i kalenderen. Overskriften for ukenummer-kolonnen kan endres med prop-en ‘weekNumberHeader’

weekNumberHeader?string 'uke'

Overskrift som vises for ukenummer-kolonnen. Vises kun hvis ‘showWeekNumbers’ er true.

classNameForDate?((date: CalendarDate) => string) undefined

Brukes for å legge til klassenavn på spesifikke datoer i kalenderen. Tar inn en dato og skal returnere klassenavnet som skal legges til den datoen. @example (date) => isWeekend(date, ‘no-NO’) ? ‘weekend’ : ‘’

OBS: hvis stylingen er meningsbærende bør du bruke ariaLabelForDate i tillegg for å beskrive meningen til skjermlesere o.l.

ariaLabelForDate?((date: CalendarDate) => string) undefined

Legger til teksten som returneres på datoen i kalenderen sin aria-label. Bør brukes sammen med classNameForDate hvis styling-endringene gjort der er meningsbærende. @example (date) => isWeekend(date, ‘no-NO’) ? ‘helgedag’ : ‘’

locale?string
calendarRef?MutableRefObject<HTMLDivElement | null>

<NativeDatePicker />

import { NativeDatePicker } from '@entur/datepicker';
NavnTypeDefault-verdiBeskrivelse
className?string

Ekstra klassenavn

labelstring

Label over NativeDatePicker

feedback?string

Varselmelding, som vil komme under NativeDatePicker

variant?VariantType

Valideringsvariant

disableLabelAnimation?boolean false

Plasserer labelen statisk på toppen av inputfeltet

prepend?ReactNode<DateIcon />

Tekst eller ikon som kommer før inputfelter

Rediger denne siden på Bitbucket