Menu

Modal
A modal displays content that temporarily blocks interactions with the main view of a site

Download

Types

Modal

A standard modal

$('.ui.modal') .modal('show') ;

Basic

A modal can reduce its complexity

$('.ui.basic.modal') .modal('show') ;

Content

Header

A modal can have a header

Content

A modal can contain content

Image Content New in 2.0

A modal can contain image content

Modals with image content must use the image content class in 2.0. This is to make sure flex-box rules do not affect regular content.

Actions

A modal can contain a row of actions

Close actions are applied by default to all button actions, in addition an onApprove or onDeny callback will fire if the elements match either selector.

approve : '.positive, .approve, .ok', deny : '.negative, .deny, .cancel'

To prevent a modal action from causing the modal to close, you can return false; from either callback.

Variations

Full Screen

A modal can use the entire size of the screen

$('.fullscreen.modal') .modal('show') ;

Size

A modal can vary in size

$('.small.modal') .modal('show') ;
$('.large.modal') .modal('show') ;

States

Active

An active modal is visible on the page

Examples

Scrolling Modal

When your modal content exceeds the height of the browser the scrollable area will automatically expand to include just enough space for scrolling, without scrolling the page below.

$('.long.modal') .modal('show') ;

Multiple Modals

A modal can open a second modal. If you use allowMultiple: true parameter the second modal will be opened on top of the first modal. Otherwise the modal will be closed before the second modal is opened.

// initialize all modals $('.coupled.modal') .modal({ allowMultiple: true }) ; // open second modal on first modal buttons $('.second.modal') .modal('attach events', '.first.modal .button') ; // show first immediately $('.first.modal') .modal('show') ;
$('.coupled.modal') .modal({ allowMultiple: false }) ; // attach events to buttons $('.second.modal') .modal('attach events', '.first.modal .button') ; // show first now $('.first.modal') .modal('show') ;

Forcing a Choice

You can disable a modal's dimmer from being closed by click to force a user to make a choice

$('.basic.test.modal') .modal('setting', 'closable', false) .modal('show') ;

Approve / Deny Callbacks

Modals will automatically tie approve deny callbacks to any positive/approve, negative/deny or ok/cancel buttons.

If onDeny, onApprove or onHide returns false it will prevent the modal from closing
$('.ui.basic.test.modal') .modal({ closable : false, onDeny : function(){ window.alert('Wait not yet!'); return false; }, onApprove : function() { window.alert('Approved!'); } }) .modal('show') ;

Attach events

A modal can attach events to another element

$('.test.modal') .modal('attach events', '.test.button', 'show') ;
Launch modal

Transitions

A modal can use any named ui transition.

$('.selection.dropdown') .dropdown({ onChange: function(value) { $('.test.modal') .modal('setting', 'transition', value) .modal('show') ; } }) ;

Dimmer Variations

Modals can specify additional variations like blurring or inverted which adjust how the dimmer displays.

Full screen blurring modals are not performant for current-gen computers at widescreen resolutions with integrated graphics.
$('.ui.modal') .modal({ inverted: true }) .modal('show') ;
$('.ui.modal') .modal({ blurring: true }) .modal('show') ;

Usage

Initializing a modal

A modal can be included anywhere on the page. On initialization a modal's current size will be cached, and the element will be detached from the DOM and moved inside a dimmer.

Why move modal content?

Having a modal inside the page dimmer allows for 3D animations without having the 3D perspective settings alter the rest of the page content. Additionally, content outside the dimmer can be blurred or altered without affecting the modal's content.

If you need to have your modal stay in its current location you can preserve its position using the setting detachable: false

$('.ui.modal') .modal() ;

Behavior

All the following behaviors can be called using the syntax:

$('.ui.modal') .modal('behavior name', argumentOne, argumentTwo) ;
Behavior Description
show Shows the modal
hide Hides the modal
toggle Toggles the modal
refresh Refreshes centering of modal on page
show dimmer Shows associated page dimmer
hide dimmer Hides associated page dimmer
hide others Hides all modals not selected modal in a dimmer
hide all Hides all visible modals in the same dimmer
cache sizes Caches current modal size
can fit Returns whether the modal can fit on the page
is active Returns whether the modal is active
set active Sets modal to active

Settings

Modal Settings
Modal settings modify the modal's behavior

Setting Default Description
detachable true If set to false will prevent the modal from being moved to inside the dimmer
autofocus true When true, the first form input inside the modal will receive focus when shown. Set this to false to prevent this behavior.
observeChanges false Whether any change in modal DOM should automatically refresh cached positions
allowMultiple false If set to true will not close other visible modals when opening a new one
keyboardShortcuts true Whether to automatically bind keyboard shortcuts
offset 0 A vertical offset to allow for content outside of modal, for example a close button, to be centered.
context body Selector or jquery object specifying the area to dim
closable true Setting to false will not allow you to close the modal by clicking on the dimmer
dimmerSettings
{ closable : false, useCSS : true }
You can specify custom settings to extend UI dimmer
transition scale Named transition to use when animating menu in and out, full list can be found in ui transitions docs.
duration 400 Duration of animation
queue false Whether additional animations should queue

Callbacks
Callbacks specify a function to occur after a specific behavior.

Setting Context Description
onShow Modal Is called when a modal starts to show.
onVisible Modal Is called after a modal has finished showing animating.
onHide($element) Modal Is called after a modal starts to hide. If the function returns false, the modal will not hide.
onHidden Modal Is called after a modal has finished hiding animation.
onApprove($element) Click Is called after a positive, approve or ok button is pressed. If the function returns false, the modal will not hide.
onDeny($element) Modal Is called after a negative, deny or cancel button is pressed. If the function returns false the modal will not hide.

DOM Settings
DOM settings specify how this module should interface with the DOM

Setting Default Description
namespace modal Event namespace. Makes sure module teardown does not effect other events attached to an element.
selector
selector : { close : '.close, .actions .button', approve : '.actions .positive, .actions .approve, .actions .ok', deny : '.actions .negative, .actions .deny, .actions .cancel' },
className
className : { active : 'active', scrolling : 'scrolling' }

Debug Settings
Debug settings controls debug output to the console

Setting Default Description
name Modal Name used in debug logs
debug False Provides standard debug output to console
performance True Provides standard debug output to console
verbose True Provides ancillary debug output to console
error
error : { method : 'The method you called is not defined.'' }

Dimmer Message
Dimmer sub-header