How to Use PrimeFaces Dialogs and Overlays in JSF Pages
Use PrimeFaces dialogs in JSF: p:dialog with widgetVar, opening from the client or server, confirm dialogs, forms inside dialogs and common mistakes.

Dialogs keep users on a page while they edit a record or confirm an action. PrimeFaces provides them as components, driven by AJAX and a small JavaScript API. This uses PrimeFaces 14 on Jakarta Faces 4 and JDK 25. The ajax mechanics underneath are in f:ajax partial updates.
A basic dialog
<h:form id="list">
<p:dataTable id="customers" var="c" value="#{customerBean.customers}">
<p:column headerText="Name"><h:outputText value="#{c.name}"/></p:column>
<p:column>
<p:commandButton value="Edit" icon="pi pi-pencil"
actionListener="#{customerBean.select(c)}"
update=":editForm:panel"
oncomplete="PF('editDialog').show()"/>
</p:column>
</p:dataTable>
</h:form>
<p:dialog id="editDialog" widgetVar="editDialog" header="Edit customer"
modal="true" resizable="false" draggable="false" closeOnEscape="true">
<h:form id="editForm">
<p:outputPanel id="panel">
<p:inputText value="#{customerBean.selected.name}" required="true"/>
<p:messages/>
</p:outputPanel>
<p:commandButton value="Save" actionListener="#{customerBean.save}"
update=":list:customers editForm:panel"
oncomplete="if (!args.validationFailed) PF('editDialog').hide()"/>
</h:form>
</p:dialog>The Edit button runs the listener on the server to load the selected row, updates the dialog panel, and then opens the dialog on the client when the response arrives. Using oncomplete means the dialog opens after the content is ready. The Save button hides it only when validation passed: args.validationFailed is set by PrimeFaces.
Rules that save time
The dialog needs its own form. A dialog is rendered at the end of the document body by default, outside the form that contains the button. An input inside the dialog but outside any form will not submit. Give it a form, as above.
**Use widgetVar and PF().** The client id of a component inside a form is form:id, and JavaScript on the page cannot rely on it. PF('editDialog') looks up the widget by its variable name, which is stable.
Update with the right id. A leading colon, as in :editForm:panel, is an absolute search from the root, needed when the target is in a different form. Id resolution rules are in JSF lifecycle.
Keep the bean scope right. A selected entity held in a request scoped bean disappears between the Edit click and the Save click. Use a view scoped bean, as discussed in bean scopes.
Confirm dialogs
<p:confirmDialog global="true" showEffect="fade" hideEffect="fade">
<p:commandButton value="Yes" type="button" styleClass="ui-confirmdialog-yes"/>
<p:commandButton value="No" type="button" styleClass="ui-confirmdialog-no"/>
</p:confirmDialog>
<p:commandButton value="Delete" action="#{customerBean.delete(c)}" update=":list:customers">
<p:confirm header="Confirm" message="Delete this customer?" icon="pi pi-exclamation-triangle"/>
</p:commandButton>One global dialog serves every button that has a p:confirm child. The action runs only after the user clicks Yes.
Opening from the server
public void save() {
service.save(selected);
PrimeFaces.current().executeScript("PF('editDialog').hide()");
PrimeFaces.current().ajax().update("list:customers");
}This suits flows where a bean decides what to show, for example after a validation of business rules.
Overlay panels and the dialog framework
p:overlayPanel anchors a small floating panel to an element, good for a help text or a quick filter. For a larger piece, the dialog framework opens a separate view in an iframe:
PrimeFaces.current().dialog().openDynamic("customerEdit", options, params);The dialog view is a normal page, which makes it reusable, at the cost of a second request and a harder data exchange. Use plain p:dialog unless you need that reuse.
Common mistakes
A dialog that appears behind a menu is a z-index problem, fixable with the appendTo="@(body)" attribute. A dialog whose form never submits is the missing form. A p:dialog rendered inside a ui:repeat for each row creates hundreds of copies, so have one dialog, and set its content from a bean.
The dialog that never closes after a save
The most common dialog bug is the one where the data is saved and the dialog stays open, or closes before the validation errors can be read. Both come from deciding in the page what only the server knows. The server knows whether validation passed, so let it close the dialog, using PrimeFaces.current().executeScript or a callback parameter.
<p:dialog header="Edit customer" widgetVar="customerDlg" modal="true" appendTo="@(body)" resizable="false">
<h:form id="customerForm">
<p:messages id="dlgMessages" />
<p:inputText value="#{customerBean.edit.name}" required="true" label="Name" />
<p:commandButton value="Save" action="#{customerBean.save}"
update="customerForm :listForm:table"
oncomplete="if (!args.validationFailed) PF('customerDlg').hide()" />
</h:form>
</p:dialog>The oncomplete handler runs after the AJAX response, and args.validationFailed is true when JSF validation or a failed FacesMessage stopped the action. The dialog hides only on success; otherwise it stays open and the p:messages component shows the errors. The same decision can be taken in the bean, which is better when the rule is a business one:
public void save() {
try {
customers.save(edit);
PrimeFaces.current().executeScript("PF('customerDlg').hide()");
} catch (DuplicateEmail e) {
FacesContext.getCurrentInstance().addMessage(null,
new FacesMessage(FacesMessage.SEVERITY_ERROR, "That email is already used", null));
FacesContext.getCurrentInstance().validationFailed();
}
}Calling validationFailed() makes args.validationFailed true for the client script, so one oncomplete expression handles both validation errors and business errors.
Put the form inside the dialog, and render the dialog outside other forms
A dialog holding input fields needs its own h:form. If it sits inside another form, the browser has nested forms, which are invalid HTML and make fields submit with the wrong form or not at all. appendTo="@(body)" moves the dialog's markup to the end of the body at run time, which also fixes dialogs that appear underneath other elements because a parent has its own stacking context. Remember that moving the dialog changes its place in the DOM: update it by its full client id, with the form prefix when it sits in a naming container, such as :customerForm. A wrong update id is a silent failure, shown only as a warning in the browser console.
Load the content only when it is opened
A page with ten dialogs, each with a data table, renders everything on the first request. Use dynamic="true" so the content is loaded on first show, and call a listener to prepare the data:
<p:dialog widgetVar="historyDlg" dynamic="true" modal="true" header="Order history">
<p:dataTable value="#{historyBean.rows}" var="row"> ... </p:dataTable>
</p:dialog>
<p:commandButton value="History" actionListener="#{historyBean.load(order.id)}"
update=":historyPanel" oncomplete="PF('historyDlg').show()" />The listener loads the rows for the selected order, the panel is updated, and only then does the dialog open, so the first view has the right data. For a view-scoped bean this costs one request per opening, and for a request-scoped one the data is lost between requests, which is the reason such a dialog sometimes opens empty: the bean that held the selection was recreated. Use a view scope for any bean that dialogs rely on.
Confirm with one global dialog
Fifty delete buttons do not need fifty confirmation dialogs. A global p:confirmDialog is shared by every command that carries a p:confirm child.
<p:confirmDialog global="true" showEffect="fade">
<p:commandButton value="Yes" type="button" styleClass="ui-confirmdialog-yes" />
<p:commandButton value="No" type="button" styleClass="ui-confirmdialog-no" />
</p:confirmDialog>
<p:commandButton value="Delete" action="#{orderBean.delete(order)}" update="table">
<p:confirm header="Delete order" message="Delete order #{order.id}? This cannot be undone." icon="pi pi-exclamation-triangle" />
</p:commandButton>The message is taken from each button, so the dialog text can include the record being deleted. Keep the destructive action on the server behind its own authorisation check, since a dialog in the browser is a courtesy and not a guard.
Accessibility and keyboard behaviour
A modal dialog should trap focus, close on Escape, and return focus to the button that opened it. PrimeFaces does most of this by default for p:dialog when modal="true" and closeOnEscape="true", and loses it when an oncomplete script replaces the DOM under the dialog or when the dialog is opened from a button that is itself re-rendered by the AJAX update. In that case focus falls back to the page body and keyboard users lose their place. Keep the opening button out of the update list, or give it a stable id, and tab through the page once with the keyboard after building a dialog. The check takes thirty seconds and finds the defects that mouse-only testing never shows.
Where this does not apply
For a simple inline edit, a p:rowEditor in the table avoids a dialog. Documentation: the PrimeFaces dialog component and the Faces specification.


