Date Picker

Playbook's date picker is built using flatpickr, a vanilla js library. Common date picker use cases and features have been adapted into simple prop based configuration detailed in the docs below. You can implement additional features and functionality by accessing a flatpickr instance directly (demonstrated in the 'flatpickr methods' example below). This is done with the following code.

const fpInstance = document.querySelector('#pickerId')._flatpickr

pickerId is a prop passed to the date picker kit. Flatpickr uses this id to target an input and attach a flatpickr instance to that input.

To learn more visit flatpickr's docs or see the hook doc section below for an applied example.

The Date Picker works best with Javascript Date Objects or ISO Date strings. If you're programming in js use Date Objects. If you're using rails convert your date object (with timezone) to UTC and then to an ISO Date string. For example, DateTime.now.utc.iso8601. This ensures that the string passed to the Date Picker kit behaves as expected.

Default

Date Picker

Hide Input Icon

Date Picker

Default Date

Default Date String
Default Date Dynamic
Default Behavior

The defaultDate/default_date prop has a null or empty string value by default. You can pass an ISO date string (preferred rails method) or date object (preferred JS method) if you want a default value on page load. Use Ruby UTC DateTime objects and convert them to ISO date strings with DateTime.now.utc.iso8601.

If you use a Date object without UTC time standardization the Date Picker kit may misinterpret that date as yesterdays date (consequence of timezone differentials and the Javascript Date Object constructor). See this GitHub issue for more information and the anti-pattern examples below.

Allow Input

Date Picker

Setting the allowInput prop to true permits users to key values directly into the input. This prop is set to false by default.

Input Field

Aria, Name, and Data Attributes
Custom Placeholder
Blank Placeholder
Disable Input

The date picker is built with the text input kit. Text input props you pass to the date picker kit will be forwarded to the input, with a few exceptions. The value attribute is automatically handled and bound to whatever date string is contained by the input field. You cannot pass a custom value prop. id props passed to the date picker kit will be assigned to it's parent/wrapper div. The pickerId prop is passed directly to the input and is required to instatiate the date picker.

You must use inputAria or input_aria and inputData or input_data props if you wish to pass data or aria attributes to the text input kit. If you use data or aria props they will be passed to the date picker kit itself instead. Also be aware the default behavior of text input aria and data props is to pass those props to attributes on the wrapping div not on the input itself.

The placeholder prop has a default string value: "Select Date". You can replace this with your own string or an empty string if you'd prefer it blank.

Label

Your Label Here

Default label prop is "Date Picker". To remove the label set the hideLabel prop in React or the hide_label prop in Rails to true.

Range (Quick Pick)

Date Picker

This date range variant uses hidden inputs to handle start and end dates. While they are not required props, it is advisable to specify a unique start_date_id, start_date_name, end_date_id, and end_date_name for each quick pick instance you place in a form and/or on a page.

Like all other date pickers, the quick pick does require a picker_id.

Range (Quick Pick w/ “This” Range limit)

Date Picker

Applying this_ranges_end_today (Rails) or thisRangesEndToday (React) causes all “This” preset ranges (i.e., this week, this month, this quarter, this year) to use an endDate of today, instead of their natural end date in the future.

Custom Quick Pick Dates

Date Picker

The customQuickPickDates/custom_quick_pick_dates prop allows for the user/dev to define their own quick pick dates.
The prop accepts an object with two key/value pairs: dates & override (separate doc example below).

The dates property accepts an array of objects. Each object in the array has label and value properties. The label is what will be displayed in the UI of the dropdown menu. The value property is just the date that is going to be passed to the datepicker. The value property can be an array of two strings that represent a range, allowing for the dev to be extremely specific. Additionally, the dates array allows for a clean, simple API under that automatically converts dates in a common vernacular.

The timePeriod property accepts "days", "weeks", "months", "quarters" or "years", representing past time periods.
The amount property accepts any number.

Custom Quick Pick Dates (append to defaults)

Date Picker

The customQuickPickDates/custom_quick_pick_dates prop allows for an override boolean. The override allows for the user to completely override the quick pick dates that ship with the component. Default of override is set to true. If you would like to simply append your dates to the default quick pick dates, set this prop to false explicitly.

Format

Date Picker
Date Picker
Date Picker
Date Picker

A full list of formatting tokens, i.e. "m/d/Y" can be found here.

Disabled Dates

Disable Single Date
Disable Multiple Dates
Disable Single Range
Disable Multiple Ranges
Disable Specific Weekdays

Min Max

Dynamic dates
Absolute formatted dates

Error

Date Picker
Invalid date. Please pick a valid date.

Flatpickr Methods


Hooks

onChange
onOpen

You can find a full list of flatpickr events and hooks in their documentation.

Year Range

Date Picker

Defaults to [1900, 2100]. Combine with min-max prop for best results.

Anti-Patterns

Unformatted Date Object
Date Object Without Time - Displays Yesterday's Date
Unformatted DateTime Object
String Conversion Without ISO Formatting

Margin Bottom

Date Picker
Date Picker
Date Picker
Date Picker
Date Picker
Date Picker

Inline

Date Picker

Month & Year Only

Date Picker

By default selectType prop is disabled. To activate it set selectionType prop in JSX/TSX to month. To activate it set selection_type prop in a rails file to month.

Week

Date Picker

By default selectType prop is disabled. To activate it set selectionType prop in JSX/TSX to week. To activate it set selection_type prop in a rails file to week.

Time Selection

Date Picker

To select time as well, you should pass the enableTime boolean prop. You can also enable timezone display by passing showTimezone.

Custom Positions

Datepicker (opens on the right)
Datepicker (opens on the left)
Datepicker (opens above on the left)
Datepicker (opens below on the right)

Datepicker supports position options from Flatpickr Options Documentation. There are multiple positioning options to choose from.

Note: In order for the above prop to work properly, you must also send staticPosition={false} to your Datepicker kit instance.

Affix Datepicker Upon Scrolling

Upon adding static={false} to the date picker, you will notice that the date picker detaches from the input field while scrolling. This is a known Flatpickr nuance. By adding the scrollContainer prop, you can tell the date picker which DOM container it should watch for scroll events. In this example, you can see that scrollContainer=".pb--page--content--main" is being passed in order to keep the date picker correctly positioned on page scroll.

Useage: scrollContainer: .validQuerySelectorHere

Custom Position (based on element)

👋 Datepicker will position from here based on ID.
Datepicker (opens on the right)
👋 Datepicker will position from here based on class name.
Datepicker (opens on the right)



Available Props

Props Type Values

max_width

array
xs
sm
md
lg
xl
xxl
0
none

z_index

array
1
2
3
4
5
6
7
8
9
10

number_spacing

array
tabular

shadow

array
none
deep
deeper
deepest

line_height

array
tightest
tighter
tight
normal
loose
looser
loosest

display

array
block
inline_block
inline
flex
inline_flex
none

cursor

array
auto
default
none
contextMenu
help
pointer
progress
wait
cell
crosshair
text
verticalText
alias
copy
move
noDrop
notAllowed
grab
grabbing
eResize
nResize
neResize
nwResize
sResize
seResize
swResize
wResize
ewResize
nsResize
neswResize
nwseResize
colResize
rowResize
allScroll
zoomIn
zoomOut

flex_direction

array
row
column
rowReverse
columnReverse

flex_wrap

array
wrap
nowrap
wrapReverse

justify_content

array
start
end
center
spaceBetween
spaceAround
spaceEvenly

justify_self

array
auto
start
end
center
stretch

align_items

array
flexStart
flexEnd
start
end
center
baseline
stretch

align_content

array
start
end
center
spaceBetween
spaceAround
spaceEvenly

align_self

array
auto
start
end
center
stretch
baseline

flex

array
auto
initial
0
1
2
3
4
5
6
7
8
9
10
11
12
none

flex_grow

array
1
0

flex_shrink

array
1
0

order

array
1
2
3
4
5
6
7
8
9
10
11
12

hover

array

border_radius

array
none
xs
sm
md
lg
xl
rounded

text_align

array
start
end
left
right
center
justify
justify-all
match-parent

overflow

array
visible
hidden
scroll
auto

truncate

array
1
2
3
4
5

left

array
0
xxs
xs
sm
md
lg
xl
auto
initial
inherit

top

array
0
xxs
xs
sm
md
lg
xl
auto
initial
inherit

right

array
0
xxs
xs
sm
md
lg
xl
auto
initial
inherit

bottom

array
0
xxs
xs
sm
md
lg
xl
auto
initial
inherit

overflow_x

array
visible
hidden
scroll
auto

overflow_y

array
visible
hidden
scroll
auto

margin

array
none
xxs
xs
sm
md
lg
xl

margin_bottom

array
none
xxs
xs
sm
md
lg
xl

margin_left

array
none
xxs
xs
sm
md
lg
xl

margin_right

array
none
xxs
xs
sm
md
lg
xl

margin_top

array
none
xxs
xs
sm
md
lg
xl

margin_x

array
none
xxs
xs
sm
md
lg
xl

margin_y

array
none
xxs
xs
sm
md
lg
xl

padding

array
none
xxs
xs
sm
md
lg
xl

padding_bottom

array
none
xxs
xs
sm
md
lg
xl

padding_left

array
none
xxs
xs
sm
md
lg
xl

padding_right

array
none
xxs
xs
sm
md
lg
xl

padding_top

array
none
xxs
xs
sm
md
lg
xl

padding_x

array
none
xxs
xs
sm
md
lg
xl

padding_y

array
none
xxs
xs
sm
md
lg
xl

classname

string

id

string

data

hashprop

aria

hashprop

html_options

hashprop

children

proc
Props Type Values Default

dark

boolean
false

position

string
auto

allow_input

boolean
false

custom_quick_pick_dates

hashprop

default_date

string

disable_date

array

disable_input

boolean
false

disable_range

array

disable_weekdays

array

enable_time

boolean
false

end_date_id

string
end_date_id

end_date_name

string
end_date_name

error

string

format

string
m/d/Y

hide_icon

boolean
false

hide_label

boolean
false

inline

boolean
false

label

string
Date Picker

input_aria

hashprop

input_data

hashprop

max_date

string

min_date

string

name

string

mode

string
single

picker_id

string

placeholder

string
Select Date

plugins

boolean
false

position_element

string

scroll_container

string

selection_type

enum
week
month
quickpick
none
none

show_timezone

boolean
false

start_date_id

string
start_date_id

start_date_name

string
start_date_name

static_position

boolean
true

this_ranges_end_today

boolean
false

required

boolean
false

year_range

array
[1900, 2100]