Deprecated: please see the current version.

Archives: SimpleModal v1.1.1 | SimpleModal v1.0.1


SimpleModal is a lightweight jQuery plugin that provides a simple interface to create a modal dialog.

The goal of SimpleModal is to provide developers with a cross-browser overlay and container that will be populated with data provided.


Tests / Examples




As a jQuery chained function, where data is a jQuery object:

$('<div>my data</div>').modal({options});

As a stand-alone jQuery function, where data is a jQuery object, a DOM element, or a plain string (which can contain HTML):

$.modal(data, {options});
$.modal('<div>my data</div>', {options});
$.modal('my data', {options});
$.modal($('#myDiv'), {options});
$.modal(jQueryObject, {options});
$.modal(document.getElementById('myDiv'), {options});


  • New in 1.2, you have the option to use external CSS or to pass in CSS attributes for the modal overlay, container, and data elements as options. The options are: overlayCss, containerCss and dataCss and take a key/value object of properties. See the jQuery CSS Docs for details.
  • SimpleModal internally handles the setting of the critical CSS properties, to prevent having to manually define them. Now in 1.2, SimpleModal dynamically centers the modal dialog and also adds a position option, for manual positioning.
  • SimpleModal internally defines the following CSS classes:
    • simplemodal-overlay: (previously modalOverlay) used to style the overlay div – helpful for applying common styles to different modal dialogs
    • simplemodal-container: (previously modalContainer) used to style the container div – helpful for applying common styles to different modal dialogs
    • simplemodal-data: (previously modalData) used to style the data element – helpful for applying common styles to different modal dialogs
    • modalCloseImg: used to style the built-in close icon (part of the closeHTML option, so this class is not changable)
Example: Applying CSS directly via the options

* Note: because modalCloseImg is not an actual element, you’d still need to use external CSS to style it

  overlayCss: {
    backgroundColor: '#000',
    cursor: 'wait'
  containerCss: {
    height: 400,
    width: 600,
    backgroundColor: '#fff',
    border: '3px solid #ccc'
Example: Applying CSS via an external stylesheet
#simplemodal-overlay {

#simplemodal-container {
  border:3px solid #ccc;

#simplemodal-container a.modalCloseImg {
  background:url(../img/x.png) no-repeat; 
  • For IE 6, the following will handle the PNG used for a.modalCloseImg:
<!--[if lt IE 7]>
<style type='text/css'>
  #simplemodal-container a.modalCloseImg{
    filter: progid:DXImageTransform.Microsoft.AlphaImageLoader(
        src='img/x.png', sizingMethod='scale'


Both of the SimpleModal modal() functions accept an optional options object, which can contain any/all of the following (default value):

  • iframe: [DEPRECATED in 1.2.2]
    Update your object and embed elements with the wmode property.
  • overlay: [DEPRECATED in 1.2]
    See opactiy, below
  • opacity: (50) [renamed from overlay in 1.2]
    The opacity value, from 0 – 100. 0 = transparent 100 = opaque
  • overlayId: (‘simplemodal-overlay’)
    The DOM element id for the overlay div
  • overlayCss: ({})
    The CSS styling for the overlay div
  • containerId: (‘simplemodal-container’)
    The DOM element id for the container div
  • containerCss: ({})
    The CSS styling for the container div
  • dataCss: ({})
    The CSS styling for the data div
  • zIndex: (1000) [new in 1.2]
    Starting z-index value
  • close: (true)
    Show the code in the closeHTML option (below)?
  • closeTitle: [DEPRECATED in 1.2]
    See closeHTML, below
  • closeHTML: (‘<a class=”modalCloseImg” title=”Close”></a>’)
    [new in 1.2] – The HTML for the default close link. SimpleModal will automatically add the closeClass to this element.
  • closeClass: (‘simplemodal-close’)
    The CSS class used to bind to the close event
  • position: (null) [new in 1.2]
    Position of container [top, left]. Can be number of pixels or percentage. If not set, SimpleModal will center the container. To only set one value, leave the other blank. For example: [top,] or [,left].
  • persist: (false)
    Persist the data across modal calls? Only used for existing DOM elements. If true, the data will be maintained across modal calls, if false, the data will be reverted to its original state
  • onOpen: (null)
    The callback function called in place of SimpleModal’s open function
  • onShow: (null)
    The callback function called after the modal dialog has opened
  • onClose: (null)
    The callback function called in place of SimpleModal’s close function


The callback functions are called using the JavaScript apply function. One parameter, the dialog object, is sent, which contains the overlay, container, data and iframe objects. In addition, inside the callback, this will refer to the SimpleModal object, which will allow you to access all of the available modal elements and functions.

  • onOpen: Useful for adding effects to the opening of the modal dialog elements. Your callback function will be passed an object that contains the overlay, container, data, and iframe elements. SimpleModal will handle “showing” the iframe, if necessary.
data.modal({onOpen: function (dialog) {
  dialog.overlay.fadeIn('slow', function () {
    dialog.container.slideDown('slow', function () {'slow');
  • onShow: Useful for binding events or any other actions you might want to perform after the modal dialog elements have been displayed. Your callback function will be passed an object that contains the overlay, container, data, and iframe elements. If you are including another plugin (TinyMCE, DatePicker, etc.) in a modal dialog, this is where you want to initialze that plugin.
  • onClose: Useful for adding effects to the closing of the modal dialog elements. Your callback function will be passed an object that contains the overlay, container, data, and iframe elements. After you’ve applied effects, etc., you’ll need to call $.modal.close(); so SimpleModal can re-insert the data correctly and clean up the dialog elements.
data.modal({onClose: function (dialog) {'slow', function () {
    dialog.container.slideUp('slow', function () {
      dialog.overlay.fadeOut('slow', function () {
        $.modal.close(); // must call this!

Other Notes

Default Values
  • If you have a value that you want to be used for all modal dialogs, instead of passing the option in for each one, you can globally modify the defaults.
Example – Single Property
$.modal.defaults.closeClass = "modalClose";
Example – Multiple Properties
$.extend($.modal.defaults, {
	closeClass: "modalClose",
	closeHTML: "<a href='#'>Close</a>"
Data CSS Display Property
  • SimpleModal “hides” the data when it adds it to the modal dialog. If you use an onOpen callback, the display value will have been set to none and you’ll need to explicitly “un-hide” the element.
Cloning and Element Removal
  • By default, SimpleModal will clone the data element that you pass in. When the dialog is closed, the cloned, unchanged, data element will be re-inserted into DOM in its original place. If the persist option is true, SimpleModal will “re-insert” the original element, with changes intact. If you use an onClose callback, you’ll need to call $.modal.close(); (see the onClose in the Callback section above).
  • SimpleModal always removes the overlay, container and iframe elements when closed. If you use an onClose callback, you’ll need to call $.modal.close(); (see the onClose in the Callback section above)
Known Issues
  • In IE6, the state of checkboxes and radio buttons are not maintained using the persist option.
  • In IE7, the state of radio buttons is not maintained using the persist option.
  • To prevent Flash objects from “bleeding through” the dialog, make sure to set the wmode property for your object and embed elements to either opaque or transparent (reference).
Browser Compatibility

SimpleModal has been tested in the following browsers:

  • IE 6, 7
  • Firefox 2, 3
  • Opera 9
  • Safari 3

Changes in 1.2

* From ChangeLog.txt

  • Added new internal variables (ie6, ieQuirks and w)
  • Added better IE6 detection (preventing false positives with IE7)
  • Fixed $.modal.close() function to correctly utilize an onClose callback without causing a infinite recursion crash
  • Added new options (dataCss, zIndex, closeHTML and position)
  • Renamed overlay option to opacity
  • Removed closeTitle option
  • Renamed default class and id names from modalXxx to simplemodal-xxx
  • Added better z-index handling – initial value can be defined through the options
  • Fixed element creation to be XHTML compliant
  • Added window dimension detection
  • Fixed Safari issue (directly setting display:’none’ as opposed to using .hide())
  • Changed width/height setting for overlay and iframe
  • Fixed IE7 positioning issue in quirks mode
  • Added IE6 expression for elements – eliminating the need for an external stylesheet
  • Added dynamic centering of container as well as a position option for manual positioning
  • Added namespacing on events
  • Added window resize listener to resize dialog elements
  • Updated demo and test/example pages


Things to be aware of when upgrading to 1.2 from a previous version:

  • If you used the overlay option, you’ll need to rename it to opacity
  • If you used the closeTitle option, you’ll need to now use the closeHTML option instead
  • Remove the container positioning CSS from your stylesheet (remove the top, left, and margin-left properties)
  • Remove any IE specific container positioning CSS
  • Overlay, container and data class and id names changed! Update your code/CSS or use the overlayId and containerId options to have SimpleModal to use the old id names.
  • closeClass option value changed! Update your code or use the closeClass option to have SimpleModal to use the old class name (modalClose).

The following option overrides should help with backwards compatibility, although you’ll still have to update your CSS. Place this somewhere after you include SimpleModal but before you create a modal dialog:

$.extend($.modal.defaults, {
  closeClass: "modalClose",
  overlayId: "modalOverlay",
  containerId: "modalContainer"

220 thoughts on “SimpleModal”

  1. How can make the modal being in self-closing after a period of time(for example 5 seconds)

  2. Thanks for the great plugin!
    I’ve modified the contact form to include additional fields, and have been sucessfull in doing so. But my latest addition was to include a attachment file upload. I have been unsuccessful in pulling any $_FILE attributes into smcf_data.php for manipulation. Can anyone point me to what I’m missing?


  3. Sorry, (after reading tons more comments,) I just wanted to add that I did include enctype=”multipart/form-data” to the form tag. If I drop either the button or the send class info (class=’smcf-button smcf-send’) then the $_FILE array is populated, but obviously not displayed in SimpleModal…

    Again, Thanks!!

  4. Does anyone have any examples/success on how to embed a video object in the modal form? I am actually looking to place it in the form with the other contact fields.

  5. Hi there, is it just me, or that’s how this modal window works…
    After successful mail sent message, the window stays open with Thank You displayed, until i press close button.
    If this is normal behavior, how can i change it to automatically close the window? But if is not, what am i doing wrong? btw. using jquery 1.3.2.


  6. Hello I currently use tinyMCE in my form. However when combined with simplemodal, the textarea is locked and cannot be edited. It does not even show the default text.

    Anyone know how to fix this problem?

  7. Hello Eric,

    First of all i want to thank you for this great tool, it is very usefull.

    I added some more fields to the contact form and works fine, but i need to add a file input field to upload a file to the server, but i cant get the value of the $_FILES[‘file’][‘name’], im using a traditional form (not AJAX).

    Can you give me a clue of how can i get the value of that variable?
    Thank You

  8. Hello again

    I want to use simplemodal to show a google map inside of it, actually i did it but doesnt show the whole map, just a part of it. And in IE 8 the map controls doesnt work properly.

    Do you have any experience on that?

    Thank you

  9. Great work! This saved me alot of time. I’m wondering if there is a fix to the centering issue already mentioned a couple of times? I find it to appear for IE8, FF, and Safari.

  10. Pingback: 70 técnicas JavaScript profesionales + tutoriales avanzados. | Webizzima

  11. Cristian Ortiz

    i need start the modal when initiating a connection to data base and close automatically the modal when the connection it’s ok.

    i.e: press connection -> view modal -> go to data base -> get data -> close modal.

  12. Is there a way to make a button in a Flash movie and call the function for the modal. I know how to call a Javascript function from Flash using AS3 and have made a simple Javascript pop up to another window but I need something like a modal instead of a simple pop up window. With jQModalplugin it requires the HTML link to have a class. Which is nearly impossible with a Flash movie. Is this the same for SimpleModal or can I just call the function from Flash without a class for the link and it will work.
    Eric, if you could email me with a solution or idea I would really appreciate it.

  13. If you can actually do the Flash movie thing and have a the modal pop up from the Flash movie button that would be a huge break through and I will tout your product all over the web as the modal to use.

    Thanks in advance.

  14. I’m sure there is an easy way to do this, but how do I use images for the border around the modal that pops up instead of any existing default border? Like, if I want to use a fuzzy shadow border all around that is created by different image files. Thanks!

  15. I do the trick to use appendTo(‘form’) instead of body because i’m working on a page in It’s working but my page use Ajax and instead of doing an Ajax postback when I click on the button in the modal div, it just do a full postback. Did somebody have an idea why?

  16. I am starting to use simplemodal and I am truly impressed. Great work. And GREAT JOB ON THE DOCUMENTATION. I have one small problem, when I popup the dialog, I am not able to navigate from one input field to another via the “Tab” key. Has anyone seen this problem?

    Thank you,


  17. Hi Eric,

    In our project we have tried a lot of modal dialog plugins and we found that SimpleModal is the best (very flexible). So I just want to thank you for this nice plugin :).

    On the link below you can find a (sexy Dialog) demo inspired by Facebook and based on your Plugin (SimpleModal power! 🙂 )

    Thanks again,


  18. @Ben – are you able to see if this is still an issue with 1.3?

    @hamletborn – something like:

    setTimeout('$.modal.close()', 5000);

    @Ken – Technically speaking, you can’t directly do a file upload using Ajax. There are ways around this, but it is too involved to explain here. You could change it so the send does a standard post and not an ajax call, but you would loose the response message.

    @emack – Graco does something similar by embedding flash – that should be similar enough to use as an example.

    @george – You are correct, that is the default behavior. This solution should do what you are asking.

    @Sam – when are you initializing tinyMCE? You should be doing it in a SimpleModal onShow callback for it to work properly.

    @Marsel – are you asking how to use something other than a button to open the confirm dialog? Something like:

    <a href='#' class='confirm'>Confirm</a>

    @Alvaro Grillet – 1) See my response to @Ken. 2) No I have not tried Google Maps in a modal dialog. Any luck?

    @Franz Zieher – 1.3 should fix the centering issues.

    @Cristian Ortiz – Did you have a particular question? You bind the open to some event and then call $.modal.close() when you want it to close.

    @Drew – the scroll position should not change. Are you using # as the href and not preventing that event?

    @carlos – can you email me with more specifics on what you are trying to do.

    @lance – there are a number of ways to do this. See @Mehdi’s comment above!

    @Dave – 1.3 should resolve that issue.

    @Tamer – which version are you using? If it is 1.3b1, I have a fix for that.

    @Mehdi – very cool, thanks for sharing!

    I’m closing the comments in preparation for the 1.3 version and project page.

Comments are closed.

Scroll to Top