Menu

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

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') ;

Overlay Full Screen

A modal can overlay the entire screen

Overlay fullscreen modals cannot be closed by clicking into the dimmer, because the dimmer is completely overlayed and not visible anymore). Make sure your modal is closable by either adding a close icon or an action button to close it.
$('.overlay.fullscreen.modal') .modal('show') ;

Size

A modal can vary in size

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

Inverted

A modal can be shown inverted on white dimmer...

$('.mini.inverted.modal') .modal({ inverted: true }) .modal('show') ;

... or default black dimmer

$('.mini.inverted.modal') .modal('show') ;

Scrolling Content
New in 2.2.11

A modal can use the entire size of the screen

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

Center Aligned
New in 2.8.8

You can center align the header, the content or even actions individually

$('#centerexample') .modal('show') ;

States

Active

An active modal is visible on the page

Examples

Disabling Vertical Centering
New in 2.3

When your modal has dynamic content, or multiple steps, it can make sense to disable centering so content doesn't jump around vertically when its height changes.

$('.special.modal') .modal({ centered: false }) .modal('show') ;

Top or Bottom aligned
New in 2.7.3

If you leave the centered option to the default true, you can also force positioning of the modal by adding additional classes top aligned (which equals to the usage of centered:false) or bottom aligned to the modal itself

If bottom aligned is used, you have to make sure that the modal content fits to the screen or uses scrolling content, because scrolling of the whole screen will not be supported to keep the modal to the bottom
$('.bottom.aligned.modal') .modal('show') ;

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') ;

Internally Scrolling Content

You may prefer to have the content of your modal scroll itself, you can do this by using the scrolling content variation.

$('.longer.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') ;

Initializing a modal

Via Javascript propertiesNew in 2.8.8

You can create temporary modals without the need to create markup on your own. Temporary modals will be removed from the DOM once closed by default if there isn't a custom onHidden callback given.

$('body').modal({ title: 'Important Notice', class: 'mini', closeIcon: true, content: 'You will be logged out in 5 Minutes', actions: [{ text: 'Alright, got it', class: 'green' }] }).modal('show');

Via existing DOM node

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() ;
Usually a given close icon on smaller modals will be displayed outside of the modal. You can force to display the close icon inside the modal, just like in fullscreen modals, by adding the inside class to the close icon.

Reuse existing modal with new content New in 2.8.8

You can prepare a modal markup as a general template and reuse it's general style but provide actual content via js properties.

var now = new Date();now.setDate(now.getDate()+Math.floor(Math.random() * 31 + 1)); $('#reusemodal').modal({ title: 'Free voucher until '+now.toDateString(), content: 'Your voucher code is
'+Math.random().toString(16).substr(2).toUpperCase()+'', classContent: 'centered', class: 'small' }).modal('show');

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

Config Templates

New in 2.8.8

A config template is a special behavior to immediately show preconfigured temporary modals. Three basic templates are included: alert, confirm, prompt as equivalents to existing vanilla JS variants, but with more possibilities to customize the look & feel.

Config template modals will be always autoshown, so no manual show is needed)
$('body').modal('alert','hello') $('body').modal('confirm','Are you sure?',function(value){}) $('body').modal('prompt','Enter Code', function(value){})

Alert

Possible parameters are: title, content, handler (in that order to stay nearly identical to vanilla js usage) or a given object {title:'',content:'',handler:function(){}} where as title and content can contain HTML.

If you don't trust the content set the global modal setting for preserveHTML to false.
$('body').modal('alert','hello');
$('body').modal('alert','Watch out','This is an important message!');
$('body').modal('alert',{ title: 'Listen to me', content: 'I love Fomantic-UI', handler: function() { $('body').toast({message:'Great!'}); } });

Confirm

The parameter list and logic is the same as for alert. The selected boolean choice will be provided to a given callback handler.

// title and content $('body').modal('confirm','Attention!','Ready?');
// title, content and handler $('body').modal('confirm','Attention!','Ready?', function(choice){ $('body').toast({message:'You '+ (choice ? 'Accepted':'Declined')}); });
// content and handler $('body').modal('confirm','Ready?', function(choice){ $('body').toast({message:'You '+ (choice ? 'Accepted':'Declined')}); });
// title and handler $('body').modal('confirm',{ title: 'Ready?', handler: function(choice){ $('body').toast({message:'You '+ (choice ? 'Accepted':'Declined')}); } });

Prompt

The call for prompt is basically identical to alert and confirm. There are 2 more options available when an object is given placeholder and defaultValue. If you provide HTML Code for the content and this contains an input, this will be used as the inputfield. Otherwise it creates one dynamically for you.

// provide a placeholder $('body').modal('prompt',{ title: 'Enter your name', placeholder: 'Do not enter your mothers name!', handler: function(name){ $('body').toast({message: 'Your name is ' + (name || 'CANCELLED')}); } });
// set a defaultValue $('body').modal('prompt',{ title: 'Enter your name', defaultValue: 'mommy', handler: function(name){ $('body').toast({message: 'Your name is ' + (name || 'CANCELLED')}); } });
// custom input $('body').modal('prompt', 'Custom Input', '
Nickname
', function(name) { $('body').toast({message: 'Your name is ' + (name || 'CANCELLED')}); });

Create your own template

By extending the modals templates object once, you can define your own custom config templates. It has to return an object which will be merged into the modals settings prior to creating/showing the modal.

$.fn.modal.settings.templates.greet = function(username) { // do something according to modals settings and/or given parameters var settings = this.get.settings(); // "this" is the modal instance return { title: 'Greetings to ' + username + '!', content: ''+ username.toUpperCase() + '
is the best!', class: 'inverted', classContent: 'centered', dimmerSettings: { variation: 'inverted' } } }

Reuse this whenever you need

$('body').modal('greet','mom')
$('body').modal('greet','dad')

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
useFlex 'auto' Auto will automatically use flex in browsers that support absolutely positioned elements inside flex containers. Setting to true/false will force this setting for all browsers.
autofocus true When true, the first form input inside the modal will receive focus when shown. Set this to false to prevent this behavior.
restoreFocus true When false, the last focused element, before the modal was shown, will not get refocused again when the modal hides. This could prevent unwanted scrolling behaviors after closing a modal.
new in 2.7.2
autoShow false When true, immediately shows the modal at instantiation time.
new in 2.8.8
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
inverted false If inverted dimmer should be used
blurring false If dimmer should blur background
centered true If modal should be center aligned
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.

Alternatively you can provide an object to set individual values for hide/show transitions as well as hide/show duration. New in 2.8.8

{ showMethod : 'fade', showDuration : 200, hideMethod : 'zoom, hideDuration : 500, }

duration 400 Duration of animation. The value will be ignored when individual hide/show duration values are provided via the transition setting
queue false Whether additional animations should queue
scrollbarWidth 10 Used internally to determine if the webkit custom scrollbar was clicked to prevent hiding the dimmer. This should be set to the same (numeric) value as defined for @customScrollbarWidth in site.less in case you are using a different theme

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 : { title : '> .header', content : '> .content', actions : '> .actions', close : '> .close', approve : '.actions .positive, .actions .approve, .actions .ok', deny : '.actions .negative, .actions .deny, .actions .cancel', dimmer : '> .ui.dimmer', bodyFixed: '> .ui.fixed.menu, > .ui.right.toast-container, > .ui.right.sidebar, > .ui.fixed.nag, > .ui.fixed.nag > .close', prompt : '.ui.input > input' }
className
className : { active : 'active', animating : 'animating', blurring : 'blurring', inverted : 'inverted', legacy : 'legacy', loading : 'loading', scrolling : 'scrolling', undetached : 'undetached', front : 'front', close : 'close icon', button : 'ui button', modal : 'ui modal', title : 'header', content : 'content', actions : 'actions', template : 'ui tiny modal', ok : 'positive', cancel : 'negative', prompt : 'ui fluid input' }

Config Template Settings
Config Template Settings define default content for dynamically created modals

Setting Default Description
title '' Content of the modal header
content '' Content of the modal content
closeIcon false Whether the modal should include a close icon
actions false An array of objects. Each object defines an action with properties text,class,icon and click
actions: [{ text : 'Wait', class : 'red', icon : 'exclamation', click : function(){} }]
preserveHTML true Whether HTML included in given title, content or actions should be preserved. Set to false in case you work with untrusted 3rd party content
class '' Can hold a string to be added to the modal class to control its appearance.
classTitle '' Can hold a string to be added to the title class to control its appearance.
classContent '' Can hold a string to be added to the content class to control its appearance.
classActions '' Can hold a string to be added to the actions class to control its appearance.
fields
fields : { class : 'class', text : 'text', icon : 'icon', click : 'click' }
text
text: { ok : 'Ok', cancel: 'Cancel' }

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 : { dimmer : 'UI Dimmer, a required component is not included in this page', method : 'The method you called is not defined.', notFound : 'The element you specified could not be found' }

Dimmer Message
Dimmer sub-header