DateTimePicker (<b:dateTimePicker />)

Basic usage

The dateTimePicker is a responsive input field that allows you to input the date, the time or both.

Live preview

Mode="inline"breaking change in 1.0.2

We've removed the option mode="inline" in favor of two more explicit options: show-icon and icon-position.

Disable and readonly

The dateTimePicker has also the ability to disable and set the readonly option.

Attention Unfortunately, at the moment, the readonly attribute doesn't work on the dateTimePicker in mode="inline"

Live preview


Formatting and locale

By default, the dateTimePicker tries to guess the proper format from your locale. You can customize this by three options:

  • show-date allows you to show or hide the calendar.
  • show-time allows you to show or hide the time picker.
  • format This option overrules both show-date and show-time. You can define an arbitrary date and time format by using the format definitions of moment.js. Note that moment.js is a JavaScript library that does not follow the formatting rules Java programmers are used to. There are subtle (and sometimes not-so-subtle) differences.

Live preview

Interactive date formats cheat sheet

<b:dateTimePicker > is based on a JavaScript component using the moment.js library. Unfortunately, this library uses different format strings than Java's SimpleDateFormatter does. For the sake of backward compatibility, we've decided to stick with the moment.js format strings. To make your life easier, here's a little cheat sheet converting the date formats.

Caveat:The predefined formats are not converted automatically. That's because they are implemented differently in various languages, so trying to translate them is beyond the scope of the BootsFaces project.

Hint:The language selector doesn't support AJAX. After selecting a language, scroll down to this section again.

Note that the internationalization doesn't work with the moment.js version of the interactive example. For some reason, the Nashorn JavaScript engine seems to ignore the locale setting of moment.js.

Note that the internationalization doesn't work with the moment.js version of the interactive example. For some reason, the Nashorn JavaScript engine seems to ignore the locale setting of moment.js.

KeyJava (example)moment.jsmoment.js (example)Description
'(not printed)[] escape character
aPMA AM or PM
D107DDD day in year - one to three digits
DD107 day in year- two or three digits
DDD107DDDD day in year- three digits
d16D day in month - one or two digits
dd16DD day in month - two digits
ETueddd day name in week - short
EETueddd day name in week - short
EEETueddd day name in week - short
EEEETuesdaydddd day name in week - full
F3 day of week in month
GAD era - AD or BC
H18H hour - one or two digits, 24 hours, 0..23
HH18HH hour - two digits, 24 hours, 00..23
h6h hour - one or two digits, 12 hours, 1..12
hh06hh hour - two digits, 12 hours, 01..12
K6 hour - one or two digits, 12 hours, 0..11
KK06 hour - two digits, 12 hours, 00..11
k18k hour - one or two digits, 12 hours, 1..24
kk18kk hour - two digits, 24 hours, 01..24
M4M month in year - two digits, 1..12
MM04MM month in year - two digits, 01..12
MMMAprMMM month in year - short text
MMMMAprilMMMM month in year - full text
m34m minutes - one or two digits
mm34mm minutes - two digits
S922S millisecond
SS922SS millisecond
SSS922SSS millisecond
s41s seconds- one or two digits
ss41ss seconds - two digits
u2E day number of week - 1=Monday, 7=Sunday
W3 week in month - one or two digits
WW03 week in month - two digits, zero-padded
w16W week in year - one or two digits
ww16WW week in year - two digits, zero-padded
XZ ISO 8601 time zone - - hours only
XXZZZ ISO 8601 time zone - short
XXXZZ ISO 8601 time zone - long
Y2024 week year - two digits
YY24gg week year - two digits
YYY2024 week year - three digits
YYYY2024gggg week year - all digits
y2024YYYY year - every digit
yy24YY year - two digits
yyy2024YYYY year - three digits
yyyy2024YYYY year - every digit
Z+0000ZZ RFC 822 time zone
zUTC General time zone
zzUTC General time zone
zzzUTC General time zone
zzzzCoordinated Universal Time General time zone
moment.jsmoment.js (example)JavaJava (example)Description
A a PMAM or PM
a am or pm
D d 16day in month - one or two digits
DD dd 16day in month - two digits
DDD D 107day in year
DDDD DDD 107day in year
Do day of month with ordinal
d day in week - 0=Sunday, 6=Saturda
ddd E Tueday name - short
dddd EEEE Tuesdayday name - full
E u 2ISO day of week - 1..7
e Locale day of week - 0..6
H H 18hour - one or two digits, 24 hours, 0..23
HH HH 18hour - two digits, 24 hours, 00..23
h h 6hour - one or two digits, 12 hours, 1..12
hh hh 06hour - two or two digits, 12 hours, 01..12
k k 18hour - one or two digits, 24 hours, 1..24
kk kk 18hour - two digits, 24 hours, 01..24
M M 4month in year - two digits, 01..12
MM MM 04month in year - two digits, 01..12
MMM MMM Aprmonth in year - short text
MMMM MMMM Aprilmonth in year - full text
m m 34minutes - one or two digits
mm mm 34minutes - two digits
Q quarter in year - 1..
S S 925fractional seconds - 0...99
SS SS 925fractional seconds - 00...99
SSS SSS 925fractional seconds - 000...99
s s 41seconds - one or two digits
ss ss 41second - two digits
W w 16week in year - one or two digits, 1..53
WW ww 16week in year - two digits, 01..53
w locale week in year - one or two digits, 1..53
ww locale week in year - two digits, 01..53
X UNIX timestamp
x UNIX timestamp - milliseconds
Y year - any number of digits and sig
YY yy 24year - two digits
YYYY yyyy 2024year - all digits
Z XXX Zoffset from UTC
ZZ ZZ +0000offset from UTC
[ ' (not printed)escape character
] ' (not printed)escape character

DateTimePicker widget inside an overflow area

By default, the popup widget of DateTimePicker goes inside the parent of the input component. This means that, if the component itself is too small to display the entire popup and has an hidden overflow, the popup will go under the component area. To prevent this behaviour, you can use the "widgetParent" attribute, that attach the popup widget to the widgetParent item, but display it near to the input of component.

Live preview

Anchor here

Labels, required fields and error messagesbreaking change in 1.1.0

You can add a label by adding the attribute label. The label is also used by the JSF messages. To give you maximum flexibility, you can suppress automatic rendering of labels by adding renderLabel="false".

BootsFaces 1.0.2 and below:

Required inputs fields and their labels both bear the CSS class bf-required. By default, this adds an asterisk to the label.

If the field has a FacesMessage, one of the CSS classes bf-info, bf-warning, bf-error or bf-fatal, depending on which error severity the message has. The latter two classes color the label red.

If there's no message, the field and its label bear the pseudo CSS class bf-no-message and has-success. The latter colors the label green by default.

BootsFaces 1.1.0:

bf-info, bf-warning, bf-error or bf-fatal have been dropped in favor of the standard Bootstrap CSS classes has-success, has-warning and has-error. Plus, they are applied to the form-group instead of the labels and input fields.

Compatibility settings

If your application depends on the old HTML code, activate the context parameter net.bootsfaces.legacy_error_classes in the web.xml. The example below shows how to do this.

Live preview

DateTimePicker AJAXsince 1.0

DateTimePicker component also support AJAX events. In addition to the basic JavaScript events (click, blur, key*, mouse*), it supports also a custom event (dtchange) that is called every time the datetime value changes. But you must pay attention! This event will be fired also during navigation of the popup widget, because it changes the date on the fly. If you want to get the latest selected value, you can use standard events like "onblur".
Note that the component must be inside a form to work in AJAX!

Live preview

id and field-idsince 1.0.1

The datepicker widgets consists of the input field and some extra HTML code which makes it look like a datepicker. Both items have an id. The id of the outer HTML code is the standard id every JSF component has. The id of the input field can be modified by the attribute field-id. By default, it's the client id plus the suffix _Input, but that's subject to change, so please don't rely on it.

Live preview

Reference section

Attribute Default value Description
ajax false Whether the Button submits the form with AJAX.
allow-input-toggle
allowInputToggle (alternative writing)
false If true, the picker will show on textbox focus and icon click when used in a button group. Default: false.
auto-update
autoUpdate (alternative writing)
false Setting this flag updates the widget on every AJAX request.
binding (none) An EL expression referring to a server side UIComponent instance in a backing bean.
col-lg
colLg (alternative writing)
-1 Integer value to specify how many columns to span on large screens (≥1200 pixels wide). The number may optionally be followed by "column" or "columns". Alternative legal values: half, one-third, two-thirds, one-fourth, three-fourths.
col-md
colMd (alternative writing)
-1 Integer value to specify how many columns to span on medium screens (≥992 pixels wide). The number may optionally be followed by "column" or "columns". Alternative legal values: half, one-third, two-thirds, one-fourth, three-fourths.
col-sm
colSm (alternative writing)
-1 Integer value to specify how many columns to span on small screens (≥768p pixels wide). The number may optionally be followed by "column" or "columns". Alternative legal values: half, one-third, two-thirds, one-fourth, three-fourths.
col-xs
colXs (alternative writing)
-1 Integer value to specify how many columns to span on tiny screens (≤ 767 pixels wide). The number may optionally be followed by "column" or "columns". Alternative legal values: half, one-third, two-thirds, one-fourth, three-fourths.
collapse true If true, a Bootstrap collapse animation is used to switch between the date picker and the time picker.
day-view-header-format
dayViewHeaderFormat (alternative writing)
MMMM YYYY Changes the heading of the datepicker when in 'days' view. Default: 'MMMM YYYY'.
delay (none) Delays the AJAX request.
disable-time-interval
disableTimeInterval (alternative writing)
(none) Disables time selection between the given moments. Default: false.
disabled false Disables the input element, default is false.
disabled-dates
disabledDates (alternative writing)
(none) Disables selection of dates in the array, e.g. holidays. Default: null. Accepts a comma separated list of Date, moment or JavaScript string. For example: '11/22/2013 00:53' (with single quotes).
display block If you use the "visible" attribute, the value of this attribute is added. Legal values: block, inline, inline-block. Default: block.
enabled-dates
enabledDates (alternative writing)
(none) Disables selection of dates NOT in the array, e.g. holidays. Default: false. Accepts: array of [date, moment, JavaScript string].
field-id
fieldId (alternative writing)
(none) Unique id of the input field itself (as opposed to the id, which is belongs to the entire component, including the div surrounding the input field). Useful for frameworks like JAAS, which require you to use a specific field id.
field-size
fieldSize (alternative writing)
(none) The size of the input. Possible values are xs (extra small), sm (small), md (medium) and lg (large) .
focus-on-show
focusOnShow (alternative writing)
true If false, the textbox will not be given focus when the picker is shown. Default: true.
format (none) See momentjs' docs for valid formats. Format also dictates which components are shown, e.g. MM/dd/YYYY will not display the time picker.
hidden (none) This column is hidden on a certain screen size and below. Legal values: lg, md, sm, xs.
icon (none) Picker Icon, can be one of the Bootstrap icon names.
icon-awesome
iconAwesome (alternative writing)
(none) Font Awesome Icon to show in this DateTimePicker, can be one of the Font Awesome icon names.
icon-brand
iconBrand (alternative writing)
false Use the free brand font of FontAwesome 5. As a side effect, every FontAwesome icon on the same page is switched to FontAwesome 5.2.0. By default, the icon set is the older version 4.7.0.
icon-flip
iconFlip (alternative writing)
(none) Flip the icon: can be H (horizontal) or V (vertical).
icon-inverse
iconInverse (alternative writing)
false Switch the icon from black-on-white to white-on-black.
icon-light
iconLight (alternative writing)
false Use the paid 'light' font of FontAwesome 5. As a side effect, every FontAwesome icon on the same page is switched to FontAwesome 5.2.0. By default, the icon set is the older version 4.7.0.
icon-position
iconPosition (alternative writing)
right Put the icon to the left or to the right of the input field. Legal values: 'left' and 'right'. Default value: 'right'.
icon-pulse
iconPulse (alternative writing)
false Boolean value: if true the icon will rotate with 8 discrete steps.
icon-regular
iconRegular (alternative writing)
false Use the paid 'regular' font of FontAwesome 5. As a side effect, every FontAwesome icon on the same page is switched to FontAwesome 5.2.0. By default, the icon set is the older version 4.7.0.
icon-rotate
iconRotate (alternative writing)
(none) Rotate 90 degrees the icon: Can be L,R.
icon-size
iconSize (alternative writing)
(none) Icon Size: legal values are lg (=133%), 2x, 3x, 4x, 5x. If you're using Fontawesome 5, also 6x, 7x, 8x, 9, 10x, xs (=75%), and sm (=87.5%) are allowed.
icon-solid
iconSolid (alternative writing)
false Use the free font of FontAwesome 5. As a side effect, every FontAwesome icon on the same page is switched to FontAwesome 5.2.0. By default, the icon set is the older version 4.7.0.
icon-spin
iconSpin (alternative writing)
false Boolean value: if true the icon will spin.
id (none) Unique identifier of the component in a namingContainer.
immediate false Flag indicating that, if this component is activated by the user, notifications should be delivered to interested listeners and actions immediately (that is, during Apply Request Values phase) rather than waiting until Invoke Application phase. Default is false.
initial-date
initialDate (alternative writing)
(none) Sets the picker default date/time. Overrides useCurrent. Default: false. Accepts: date, moment, string.
keep-invalid
keepInvalid (alternative writing)
false Will cause the date picker to not revert or overwrite invalid dates. Default: false.
keep-open
keepOpen (alternative writing)
false Will cause the date picker to stay open after selecting a date if no time components are being used. Deafult: false.
label (none) An optional label of the field. The label is only shown if you also set render-attribute='true'. The label is also used for error messages.
label-col-lg
labelColLg (alternative writing)
-1 Integer value to specify how many columns to span on large screens (≥1200 pixels wide). The number may optionally be followed by "column" or "columns". Alternative legal values: half, one-third, two-thirds, one-fourth, three-fourths.
label-col-md
labelColMd (alternative writing)
-1 Integer value to specify how many columns to span on medium screens (≥992 pixels wide). The number may optionally be followed by "column" or "columns". Alternative legal values: half, one-third, two-thirds, one-fourth, three-fourths.
label-col-sm
labelColSm (alternative writing)
-1 Integer value to specify how many columns to span on small screens (≥768p pixels wide). The number may optionally be followed by "column" or "columns". Alternative legal values: half, one-third, two-thirds, one-fourth, three-fourths.
label-col-xs
labelColXs (alternative writing)
-1 Integer value to specify how many columns to span on tiny screens (≤ 767 pixels wide). The number may optionally be followed by "column" or "columns". Alternative legal values: half, one-third, two-thirds, one-fourth, three-fourths.
label-large-screen
labelLargeScreen (alternative writing)
-1 Alternative spelling to col-lg. Integer value to specify how many columns to span on large screens (≥1200 pixels wide). The number may optionally be followed by "column" or "columns". Alternative legal values: half, one-third, two-thirds, one-fourth, three-fourths.
label-medium-screen
labelMediumScreen (alternative writing)
-1 Alternative spelling to col-md. Integer value to specify how many columns to span on medium screens (≥992 pixels wide). The number may optionally be followed by "column" or "columns". Alternative legal values: half, one-third, two-thirds, one-fourth, three-fourths.
label-small-screen
labelSmallScreen (alternative writing)
-1 Alternative spelling to col-sm. Integer value to specify how many columns to span on small screens (≥768p pixels wide). The number may optionally be followed by "column" or "columns". Alternative legal values: half, one-third, two-thirds, one-fourth, three-fourths.
label-style
labelStyle (alternative writing)
(none) The CSS inline style of the label.
label-style-class
labelStyleClass (alternative writing)
(none) The CSS class of the label.
label-tiny-screen
labelTinyScreen (alternative writing)
-1 Alternative spelling to col-xs. Integer value to specify how many columns to span on tiny screens (≤ 767 pixels wide). The number may optionally be followed by "column" or "columns". Alternative legal values: half, one-third, two-thirds, one-fourth, three-fourths.
large-screen
largeScreen (alternative writing)
-1 Alternative spelling to col-lg. Integer value to specify how many columns to span on large screens (≥1200 pixels wide). The number may optionally be followed by "column" or "columns". Alternative legal values: half, one-third, two-thirds, one-fourth, three-fourths.
locale (none) The desired locale. It uses the moment.js locales.
max-date
maxDate (alternative writing)
(none) Prevents date/time selections after this date. minDate will override defaultDate and useCurrent if either of these settings are the same day since both options are invalid according to the rules you've selected. Default: false, Accepts: date, moment, string.
medium-screen
mediumScreen (alternative writing)
-1 Alternative spelling to col-md. Integer value to specify how many columns to span on medium screens (≥992 pixels wide). The number may optionally be followed by "column" or "columns". Alternative legal values: half, one-third, two-thirds, one-fourth, three-fourths.
min-date
minDate (alternative writing)
(none) Prevents date/time selections before this date. minDate will override defaultDate and useCurrent if either of these settings are the same day since both options are invalid according to the rules you've selected. Default: false, Accepts: date, moment, string.
mode component Determine the display mode of the component. Available types are: 'inline' (display the full calendar object), 'popup' (text with icon) and 'plain' (only text). Default: 'popup'.
offset (none) Integer value to specify how many columns to offset.
offset-lg
offsetLg (alternative writing)
(none) Integer value to specify how many columns to offset.
offset-md
offsetMd (alternative writing)
(none) Integer value to specify how many columns to offset.
offset-sm
offsetSm (alternative writing)
(none) Integer value to specify how many columns to offset.
offset-xs
offsetXs (alternative writing)
(none) Integer value to specify how many columns to offset.
onblur (none) Client side callback to execute when input element loses focus.
onchange (none) Client side callback to execute when input element loses focus and its value has been modified since gaining focus.
onclick (none) The onclick attribute.
oncomplete (none) JavaScript to be executed when ajax completes.
ondblclick (none) Client side callback to execute when input element is double clicked.
ondtchange (none) JavaScript event to manage date time change.
onerror (none) JavaScript to be executed when ajax results on an error (including both network errors and Java exceptions).
onfocus (none) Client side callback to execute when input element receives focus.
onkeydown (none) Client side callback to execute when a key is pressed down over input element.
onkeypress (none) Client side callback to execute when a key is pressed and released over input element.
onkeyup (none) Client side callback to execute when a key is released over input element.
onmousedown (none) Client side callback to execute when a pointer input element is pressed down over input element.
onmousemove (none) Client side callback to execute when a pointer input element is moved within input element.
onmouseout (none) Client side callback to execute when a pointer input element is moved away from input element.
onmouseover (none) Client side callback to execute when a pointer input element is moved onto input element.
onmouseup (none) Client side callback to execute when a pointer input element is released over input element.
onselect (none) Client side callback to execute when text within input element is selected by user.
onsuccess (none) JavaScript to be executed when ajax completes with success (i.e. there's neither a network error nor a Java exception).
placeholder (none) The placeholder attribute shows text in a field until the field is focused upon, then hides the text.
process (none) Comma or space separated list of ids or search expressions denoting which values are to be sent to the server.
readonly false Flag indicating that this input element will prevent changes by the user.
render-label
renderLabel (alternative writing)
net.bootsfaces.component.ComponentUtils.isRenderLabelDefault() Allows you to suppress automatic rendering of labels. Used internally by AngularFaces, too.
rendered false Boolean value to specify the rendering of the component, when set to false the component will not be rendered.
required false Boolean value Require input in the component when the form is submitted.
required-message
requiredMessage (alternative writing)
(none) Message to show if the user did not specify a value and the attribute required is set to true.
show-button-panel
showButtonPanel (alternative writing)
false Boolean value to specify if row Buttons to the bottom of calendar should be shown (all button at once).
show-clear-button
showClearButton (alternative writing)
false Show the 'Clear' button in the icon toolbar. Default: false.
show-close-button
showCloseButton (alternative writing)
false Show the 'Close' button in the icon toolbar. Default: false.
show-date
showDate (alternative writing)
true By setting this to false you can deactivate the date part of the dateTimePicker. Is ignored if the attribute 'format' is used..
show-icon
showIcon (alternative writing)
true Show or hide the calendar icon next to the input field. Legal values: 'true' and 'false'. Default value: 'true'.
show-time
showTime (alternative writing)
true By setting this to false you can deactivate the time part of the dateTimePicker. Is ignored if the attribute 'format' is used.
show-today-button
showTodayButton (alternative writing)
false Show the 'Today' button in the icon toolbar. Default: false.
show-week
showWeek (alternative writing)
false Whether or not to show week numbers to the left of week rows. Default false.
side-by-side
sideBySide (alternative writing)
false Shows the picker side by side when using the time and date together. Default: false.
small-screen
smallScreen (alternative writing)
-1 Alternative spelling to col-sm. Integer value to specify how many columns to span on small screens (≥768p pixels wide). The number may optionally be followed by "column" or "columns". Alternative legal values: half, one-third, two-thirds, one-fourth, three-fourths.
span (none) Integer value to specify how many columns to span on medium screens (≥992 pixels). The number may optionally be followed by "column" or "columns". Alternative legal values: half, one-third, two-thirds, one-fourth, three-fourths.
style (none) Inline style of the input element.
style-class
styleClass (alternative writing)
(none) Style class of this element.
tabindex (none) Position of this element in the tabbing order for the current document. This value must be an integer between 0 and 32767.
time-stepping
timeStepping (alternative writing)
1 Number of minutes the up/down arrow's will move the minutes value in the time picker. Default 1.
tiny-screen
tinyScreen (alternative writing)
-1 Alternative spelling to col-xs. Integer value to specify how many columns to span on tiny screens (≤ 767 pixels wide). The number may optionally be followed by "column" or "columns". Alternative legal values: half, one-third, two-thirds, one-fourth, three-fourths.
toolbar-placement
toolbarPlacement (alternative writing)
default Changes the placement of the icon toolbar. Default: 'default'. Accepts: 'default', 'top', 'bottom'.
tooltip (none) The text of the tooltip.
tooltip-container
tooltipContainer (alternative writing)
body Where is the tooltip div generated? That's primarily a technical value that can be used to fix rendering errors in special cases. Also see data-container in the documentation of Bootstrap. The default value is body.
tooltip-delay
tooltipDelay (alternative writing)
0 The tooltip is shown and hidden with a delay. This value is the delay in milliseconds. Defaults to 0 (no delay).
tooltip-delay-hide
tooltipDelayHide (alternative writing)
0 The tooltip is hidden with a delay. This value is the delay in milliseconds. Defaults to 0 (no delay).
tooltip-delay-show
tooltipDelayShow (alternative writing)
0 The tooltip is shown with a delay. This value is the delay in milliseconds. Defaults to 0 (no delay).
tooltip-position
tooltipPosition (alternative writing)
(none) Where is the tooltip to be displayed? Possible values: "top", "bottom", "right", "left", "auto", "auto top", "auto bottom", "auto right" and "auto left". Default to "bottom".
update (none) Component(s) to be updated with ajax.
use-current
useCurrent (alternative writing)
true On show, will set the picker to the current date/time. Default: true.
use-strict
useStrict (alternative writing)
false Defines if moment should use strict date parsing when considering a date to be valid.
value (none) Value.
view-mode
viewMode (alternative writing)
days The default view to display when the picker is shown. Note: To limit the picker to selecting, for instance the year and month, use format: MM/YYYY. Default: 'days'. Accepts: 'decades','years','months','days'.
visible (none) This column is shown on a certain screen size and above. Legal values: lg, md, sm, xs.
week-days-disabled
weekDaysDisabled (alternative writing)
(none) Days of the week that should be disabled. Values are 0 (Sunday) to 6 (Saturday). Multiple values should be comma-separated. Example: disable weekends: 0,6 or [0,6].
widgetParent (none) Parent widget of the popup to prevent overlap in case of DateTimePicker inside a small size container.