Modal

Last modified by Thiago Krieck on 2026/11/18 14:13

Warning
Draft

This page is a draft. The standards on it are proposals still under discussion, so they may change and should not be treated as final yet.

The standard

  • When to use: A modal should be used for a short task that keeps the user on the current page: confirming an action, filling in a few fields, or picking a page or an image. A task with many choices or steps should get its own page, so that users don't lose their work or their place.
  • Component: Should be the Bootstrap modal (header, body, footer), and never the old XWiki.widgets.ModalPopup or ConfirmationBox, since only the Bootstrap modal behaves as a dialog for keyboard and screen reader users.
  • Title: Should name the action and the item, such as Create user or Delete attachment, and be linked to the dialog with aria-labelledby, so that screen readers announce what the dialog is for.
  • Buttons: Should be in the footer: Cancel (default style) followed by a single primary button labelled with the action, or a danger button for a destructive one. Never OK or Yes. When the modal holds a form, the primary button should stay disabled until the form is valid. See Buttons.
  • Closing: Esc and the close button should always close the modal. The close button should use the localized Close label (core.modal.close). When the modal holds a form, a click outside should not close it (data-backdrop="static"), so that a stray click doesn't throw away what was typed.
  • Focus: Should move into the modal when it opens and go back to the button that opened it when it closes, so that keyboard users keep their place.
  • Size: Should be the default size, and modal-lg only when the content needs the room, such as a diff, an image or a long form.
  • One modal at a time: A modal should never open another modal on top of itself. Bootstrap doesn't support stacked modals, so focus, Escape and page scrolling break, screen reader users are moved from one dialog to another without warning, and everyone loses track of which Cancel closes what. See When a modal needs more.

Reference example: Administration → Users → Create user, Edit user and Delete user. Each modal has a specific title linked to the dialog, Cancel followed by a primary Create or Save (disabled until there is something valid to save) or a danger Delete, a static backdrop for the forms, and the large size only for editing. Administration → Groups follows the same model.

modal-reference-create-user.png

Modal: Administration → Users → Create user

When a modal needs more

When a task inside a modal needs more input or another choice, one of these patterns should be used instead of opening a second modal:

  • Pick a page, a user or a group: The picker should be embedded in the modal, as a suggest field or a page tree inside the modal body. Reference example: user profile → Notifications → Add filter, which shows the page tree for Location directly inside the modal.
  • Ask for more details: The extra fields should appear in the same modal, either in a section that expands or as a next step that replaces the content and offers Back.
  • Move on to a separate task: The first modal should close completely before the next one opens, and focus should move into the new one. Reference example: More actions → Export, which closes before it opens the page selection or the PDF options.
  • Confirm inside the modal: When something needs the user's confirmation before the modal can continue, the question and its button should be shown in the modal body, and the modal should continue in place once the user confirms.
  • Exception, confirmations over a modal: A short confirmation that protects what the user did in the modal, such as discarding unsaved input, may appear over the modal only when it can't be shown inside it.
Information
Reference examples for confirmations

No XWiki modal is a full reference example yet. Administration → Users → Edit user follows the behavior when the profile is being edited by someone else: it asks This page is currently locked by superadmin., and Force editing loads the form in the same modal. Its layout should not be copied: the question should be a single warning message box followed by the button, as described in Alerts and notifications.

No XWiki modal shows a confirmation over itself today.

modal-reference-embedded-picker.png

Embedded picker: user profile → Notifications → Add filter

Notes

  • Bootstrap only returns focus to the trigger when the modal is opened through data-toggle="modal". A modal opened from script should return focus itself.
  • Confirmations follow Delete confirmation.
Information
Until there is a shared modal macro

There is no shared Velocity macro for modals yet, so each template repeats the markup. Until there is one, new modals should copy the Users administration markup.

More

Get Connected