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:

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
aAMA AM or PM
D267DDD day in year - one to three digits
DD267 day in year- two or three digits
DDD267DDDD day in year- three digits
d24D day in month - one or two digits
dd24DD day in month - two digits
ESunddd day name in week - short
EESunddd day name in week - short
EEESunddd day name in week - short
EEEESundaydddd day name in week - full
F4 day of week in month
GAD era - AD or BC
H4H hour - one or two digits, 24 hours, 0..23
HH04HH hour - two digits, 24 hours, 00..23
h4h hour - one or two digits, 12 hours, 1..12
hh04hh hour - two digits, 12 hours, 01..12
K4 hour - one or two digits, 12 hours, 0..11
KK04 hour - two digits, 12 hours, 00..11
k4k hour - one or two digits, 12 hours, 1..24
kk04kk hour - two digits, 24 hours, 01..24
M9M month in year - two digits, 1..12
MM09MM month in year - two digits, 01..12
MMMSepMMM month in year - short text
MMMMSeptemberMMMM month in year - full text
m59m minutes - one or two digits
mm59mm minutes - two digits
S801S millisecond
SS801SS millisecond
SSS801SSS millisecond
s18s seconds- one or two digits
ss18ss seconds - two digits
u7E day number of week - 1=Monday, 7=Sunday
W5 week in month - one or two digits
WW05 week in month - two digits, zero-padded
w39W week in year - one or two digits
ww39WW 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
Y2017 week year - two digits
YY17gg week year - two digits
YYY2017 week year - three digits
YYYY2017gggg week year - all digits
y2017YYYY year - every digit
yy17YY year - two digits
yyy2017YYYY year - three digits
yyyy2017YYYY 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 AMAM or PM
a am or pm
D d 24day in month - one or two digits
DD dd 24day in month - two digits
DDD D 267day in year
DDDD DDD 267day in year
Do day of month with ordinal
d day in week - 0=Sunday, 6=Saturda
ddd E Sunday name - short
dddd EEEE Sundayday name - full
E u 7ISO day of week - 1..7
e Locale day of week - 0..6
H H 4hour - one or two digits, 24 hours, 0..23
HH HH 04hour - two digits, 24 hours, 00..23
h h 4hour - one or two digits, 12 hours, 1..12
hh hh 04hour - two or two digits, 12 hours, 01..12
k k 4hour - one or two digits, 24 hours, 1..24
kk kk 04hour - two digits, 24 hours, 01..24
M M 9month in year - two digits, 01..12
MM MM 09month in year - two digits, 01..12
MMM MMM Sepmonth in year - short text
MMMM MMMM Septembermonth in year - full text
m m 59minutes - one or two digits
mm mm 59minutes - two digits
Q quarter in year - 1..
S S 804fractional seconds - 0...99
SS SS 804fractional seconds - 00...99
SSS SSS 804fractional seconds - 000...99
s s 18seconds - one or two digits
ss ss 18second - two digits
W w 39week in year - one or two digits, 1..53
WW ww 39week 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 17year - two digits
YYYY yyyy 2017year - 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 messages breaking 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 AJAX since 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-id since 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

Attribute Default value Description
ajax false Activates AJAX. The default value is false (no 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.
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'.
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: false. Accepts: array of [date, moment, string].
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, 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-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'.
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) OnClick DHTML event .
oncomplete (none) JavaScript to be executed when ajax completes with success.
ondblclick (none) Client side callback to execute when input element is double clicked.
ondtchange (none) JavaScript event to manage date time change.
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.
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.
  • Tell the world which CSS classes can be used to change the look of the component.