Modals are streamlined, but flexible, dialog prompts with the minimum required functionality and smart defaults.

Modal options

You can specify a header with the title attribute. Modals have a dismiss button(a cross) in the upper right corner by default.

The <b:modal> tag has also a facet with name footer where you can add buttons for dismissing the modal or for other actions.

Notice that the <b:button> tag must have the dismiss="modal" attribute in order to dismiss the modal when clicked.

Triggering Modals

You have four ways to create a Button that triggers a Modal:

Note: if your intended use is to trigger a data submission that shows the results in a Modal, then have a look at the commandButton documentation.

The following example shows you how to use the four kinds of triggers.

Overlapping modals are not supported: be sure not to open a modal while another is still visible. Showing more than one modal at a time requires custom code.

Live preview


Using ids is always a bit tricky in JSF. Don't put your modal dialog into a form. If you do, be aware that the id is modified. The href of the b:button refers to the id in the HTML code, not to the id of the source code. JSF prepends the ids of the parent containers to the id of b:modal.

In general, it's a better idea to use a pseudo CSS class instead of an id. That's a styleClass that may or may not have CSS instructions applied to it. Pure pseudo CSS classes don't influence the layout at all. They are simply a convenient alternative to ids. Instead of writing href="#someId" you can write href=".somePseudoClass". JSF never modifies CSS class names, so they are a good alternative to using ids. However, you have to use some JavaScript to activate the modal dialog using a CSS pseudo class, as the following example shows:

Live preview

closable and backdrop

By default, there's an x symbol which allows the user to close the modal. Set closable="false" to suppress the close icon. Users can close modal dialogs by hitting the ESC key unless you set close-on-escape="false". Another default behavior of modal is that you can close a modal dialog by clicking somewhere outside the modal. Set backdrop="false" to disable this feature.

Opening a modal dialog when entering the JSF view

If you don't want to open the modal dialog when a button is clicked, but already when the JSF view is opened, you can use an inline script to open the dialog programmatically:

Alternatively, you can use the pass-through attributes that have been introduced with JSF 2.2:

Just in case you wonder why it doesn't suffice to add the pass-through attribute pt:data-show="true" to the b:modal: By default, this attribute is already set to true. It influences what happens when you call $('.modalPseudoClass').modal(); (i.e. omitting the attribute 'show'). If pt:data-show="false", the data structure of the modal is initialized, but it remains invisible. If pt:data-show="true", the modal is also shown. Calling $('.modalPseudoClass').modal('show'); or $('.modalPseudoClass').modal('hide'); overrides the default setting defined by pt:data-show="true".

Datatables in a modal

By default, modals are hidden. As a consequence, any <b:dataTable /> inside the modal is rendered incorrectly. You can fix that by recalculating the datatable after showing the modal. You need the JavaScript approach for that. Just add the line myDataTableWidgetVar.DataTable().responsive.recalc(); as shown in the example below.

If simpler approach is to set the flag scroll-horizontally="true". This adds a scrollbar to the table. The advantage of this approach is that it works without JavaScript. The disadvantage is that it doesn't work with reponsive tables using responsive="true". You can see the difference in the example below.

Live preview

Attribute Default value Description
backdrop true By default, you can close a modal dialog by clicking somewhere outside the modal. Set backdrop="false" to disable this feature.
closable true If true, the modal dialog can be closed by clicking the small cross in the upper right corner
closeOnEscape (alternative writing)
true By default, users can close modal dialogs by hitting the ESC key. Set close-on-escape="false" to disable this feature.
contentClass (alternative writing)
(none) content-class is optional: if specified, the content will be displayed with this specific class
contentStyle (alternative writing)
(none) Inline style of the content area.
headerClass (alternative writing)
(none) The style class of the header is optional. If specified, it will add a CSS style class to the header.
headerStyle (alternative writing)
(none) The style of the header is optional. If specified, it will add the CSS style to the header.
id (none) Unique identifier of the component in a namingContainer.
rendered false Boolean value to specify the rendering of the component, when set to false the component will not be rendered.
size (none) Modal's size. Possible values modal-sm, modal-lg
style (none) Inline style
styleClass (alternative writing)
(none) Style class of this element.
title (none) Bold title displayed in the modal's header.

The optional facet footer can be used to display buttons below a horizontal ruler, as shown in the example above.