2 |
3 | # Zebra Dialog [](https://twitter.com/intent/tweet?text=A+small,+compact,+mobile-friendly+and+highly+configurable+jQuery+plugin+for+creating+responsive+modal+dialog+boxes&url=https://github.com/stefangabos/Zebra_Dialog&via=stefangabos&hashtags=jquery,dialog,notifications,alert,modal,javascript)
4 |
5 | *A small, compact, mobile-friendly and highly configurable jQuery plugin for creating responsive modal dialog boxes*
6 |
7 | [](https://www.npmjs.com/package/zebra_dialog) [](https://www.npmjs.com/package/zebra_dialog) [](https://www.npmjs.com/package/zebra_dialog) [](https://www.jsdelivr.com/package/npm/zebra_dialog) [](https://github.com/stefangabos/Zebra_Dialog/blob/master/LICENSE.md)
8 |
9 | A modal dialog box is a focused interface element that prompts users to take action before returning to the main application. These dialogs are commonly used to capture user attention, deliver important information, confirm actions, or highlight warnings and errors. By temporarily blocking interaction with the rest of the page, modal windows ensure that users address critical tasks or notifications before proceeding, making them a fundamental part of modern web applications.
10 |
11 | **Zebra Dialog** is a small (~12KB minified, 3KB gzipped), compact (one JavaScript file, no dependencies other than jQuery 1.7.0+), mobile-friendly and highly configurable jQuery plugin for creating responsive modal dialog boxes, meant to replace native JavaScript *alert*, *confirm* and *prompt* dialog boxes.
12 |
13 | Can also be used as a notification widget (when configured to show no buttons and to close automatically) for updates or errors, without distracting users from their browser experience by displaying obtrusive alerts.
14 |
15 | [](https://stefangabos.github.io/Zebra_Dialog/flat.html)
16 | [](https://stefangabos.github.io/Zebra_Dialog/materialize.html)
17 | [](https://stefangabos.github.io/Zebra_Dialog/index.html)
18 |
19 | ## Features
20 |
21 | - great looking dialog boxes, out of the box, with 3 beautiful themes included
22 | - 6 types of dialog boxes available: *confirmation*, *error*, *information*, *prompt*, *question* and *warning*
23 | - content can also be added through AJAX calls, iFrames or from inline elements (together with attached events)
24 | - easily customisable appearance by editing the CSS file
25 | - create modal or non-modal dialog boxes
26 | - easily add custom buttons
27 | - position the dialog box wherever you want - not just in the middle of the screen
28 | - dialog boxes are draggable
29 | - callback functions can be used for further customisations
30 | - use callback functions to handle users' choice
31 | - works on mobile devices
32 | - works in pretty much any browser (Chrome, Firefox, Safari, Edge, Opera, Internet Explorer 6+)
33 |
34 | For the [classic theme](https://stefangabos.github.io/Zebra_Dialog/index.html), the icons used for *confirmation*, *information*, *error* and *question* dialog boxes are made by [DryIcon](http://dryicons.com/free-icons/preview/aesthetica/) while the *warning* icon is made by Function Design & Development Studio (website is not online anymore).
35 |
36 | For the [flat theme](https://stefangabos.github.io/Zebra_Dialog/flat.html), the icons used are made by [Elegant Themes](http://www.elegantthemes.com/blog/freebie-of-the-week/beautiful-flat-icons-for-free)
37 |
38 | For the [materialize theme](https://stefangabos.github.io/Zebra_Dialog/materialize.html) theme, the icons used are taken from [Google's Material Design](https://material.io/tools/icons/?style=baseline) *"design language"*.
39 |
40 | ## 🎂 Support the development of this project
41 |
42 | Your support means a lot and it keeps me motivated to keep working on open source projects.
](https://github.com/stefangabos/Zebra_Dialog) [](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=RKMCMRZB493LY) [
](https://github.com/sponsors/stefangabos)
48 |
49 | ## Demo
50 |
51 | See the [demos](https://stefangabos.github.io/Zebra_Dialog/flat.html)
52 |
53 | ## Requirements
54 |
55 | Zebra Dialog has no dependencies other than jQuery 1.7.0+
56 |
57 | ## Installation
58 |
59 | Zebra Dialog is available as a [npm package](https://www.npmjs.com/package/zebra_dialog). To install it use:
60 |
61 | ```bash
62 | # the "--save" argument adds the plugin as a dependency in packages.json
63 | npm install zebra_dialog --save
64 | ```
65 |
66 | ## How to use
67 |
68 | First, load jQuery from a CDN and provide a fallback to a local source like:
69 |
70 | ```html
71 |
72 |
73 | ```
74 |
75 | Load the Zebra Dialog jQuery plugin:
76 |
77 | ```html
78 |
79 | ```
80 |
81 | Alternatively, you can load Zebra Dialog from [JSDelivr CDN](https://www.jsdelivr.com/package/npm/zebra_dialog) like this:
82 | ```html
83 |
84 |
85 |
86 |
87 |
88 |
89 |
90 | ```
91 |
92 | Load the style sheet file from a local source
93 |
94 | ```html
95 |
96 | ```
97 |
98 | ...or from [JSDelivr CDN](https://www.jsdelivr.com/)
99 |
100 | ```html
101 |
102 |
105 |
106 |
107 |
110 |
111 |
112 | ```
113 |
114 | Now, within the DOM-ready event do
115 |
116 | ```javascript
117 | $(document).ready(function() {
118 |
119 | // show a dialog box when clicking on an element
120 | $('#element').on('click', function(e) {
121 | e.preventDefault();
122 | new $.Zebra_Dialog('The link was clicked!');
123 | });
124 |
125 | });
126 | ```
127 |
128 | ## Configuration options
129 |
130 | ## Properties
131 |
132 | | Property | 136 |Type | 137 |Default | 138 |Description | 139 |
|---|---|---|---|
animation_speed_hide |
144 | integer | 145 |250 | 146 |147 | The speed, in milliseconds, by which the backdrop and the dialog box will be animated when closing. 148 | | 149 |
animation_speed_show |
152 | integer | 153 |0 | 154 |155 | The speed, in milliseconds, by which the backdrop and the dialog box will be animated when appearing. 156 | | 157 |
auto_close |
160 | mixed | 161 |false | 162 |
163 | The number of milliseconds after which to automatically close the dialog box or false to not automatically close the dialog box.
164 | |
165 |
auto_focus_button |
168 | mixed | 169 |true | 170 |
171 | The index (0-based) of the button (from left to right) to place the focus on when a dialog box is first shown. 172 | Set to false to disable.173 | When set to174 | Setting this to true is equivalent to setting it to 0.175 | Default is TRUE 176 | |
177 |
backdrop_close |
180 | boolean | 181 |true | 182 |183 | Should the dialog box close when the backdrop is clicked? 184 | | 185 |
backdrop_opacity |
188 | double | 189 |.9 | 190 |
191 | The opacity of the backdrop (between 0 and 1)
192 | |
193 |
buttons |
196 | mixed | 197 |198 | |
199 | Use this for localization and for adding custom buttons. 200 | If set to true, the default buttons will be used, depending on the type of the dialog box: ['Ok', 'Cancel'] for prompt, question and warning types, and ['Ok'] for the other types of dialog boxes.201 | For custom buttons, use an array containing the captions of the buttons to display: ['My button 1', 'My button 2'].202 | Set to false if you want no buttons.203 | You can also add custom CSS classes, set which button's callback to be triggered when the user presses ENTER while 204 | inside the input box (for prompt dialog boxes and when prompt_rows is 1), and/or attach callback functions to individual buttons by using
205 | objects in the form of:206 | [{207 | caption: 'My button 1',208 | custom_class: 'foo',209 | default_confirmation: true,210 | callback: function() { // code }211 | },{212 | caption: 'My button 2',213 | custom_class: 'bar',214 | callback: function() { // code }215 | }]216 | For prompt dialog box types use the default_confirmation property to tell the library
217 | which button's callback to trigger when the user presses ENTER while inside the input box. If
218 | not set, you will have to handle user input via the onBeforeClose event, or you will
219 | not be able to process user input for this case.220 | The above applies only if 221 | Callback functions receive as first argument the entire dialog box, as a jQuery object, and as second argument, 222 | the value entered in the input box - when the dialog box's type is prompt, or undefined
223 | for the other dialog types.224 | A callback function attache to a button is executed as soon as the button is clicked rather than after 225 | the dialog box is closed, as it is the case with the onClose event.226 | A callback function returning FALSE will prevent the dialog box from closing.227 | |
228 |
center_buttons |
231 | boolean | 232 |false | 233 |
234 | Setting this property to true will instruct the plugin to center any available buttons instead of aligning them to the right
235 | |
236 |
custom_class |
239 | mixed | 240 |false | 241 |
242 | An extra class to add to the dialog box's container and to the backdrop (when present). 243 | For example, setting this value to mycustom and in the CSS file having something like244 | .mycustom .ZebraDialog_Title { background: red }245 | would set the dialog box title's background to red. 246 | Take a look into a theme's style sheet file to see what can be changed.247 | |
248 |
default_value |
251 | string | 252 |"" (empty string) |
253 |
254 | Default value to show in the input box when the dialog box type is prompt.255 | See also the placeholder property.
256 | |
257 |
disable_page_scrolling |
260 | boolean | 261 |true | 262 |
263 | Prevents scrolling of the page behind the dialog box, when the dialog box is open. 264 | This has effect only when the265 | |
266 |
draggable |
269 | mixed | 270 |true for dialog boxes that have a title | 271 |
272 | Whether the dialog box should be draggable or not. 273 | Dialog boxes that have a title are draggable by default unless this property is set to false.274 | For dialog boxes not having a title, set this property to force for making them draggable.
275 | |
276 |
height |
279 | mixed | 280 |0 (automatically set) |
281 |
282 | By default, the height of the dialog box is automatically computed to fit the content (but not exceed viewport). 283 | Can be specified as a numeric value (which will be interpreted as a value in pixels) or as a percentage (of the viewport). 284 | If285 | |
286 |
keyboard |
289 | boolean | 290 |true | 291 |
292 | When set to true, pressing the ESC key will close the dialog box.
293 | |
294 |
margin |
297 | mixed | 298 |0 | 299 |
300 | Margin of the dialog box relative to the viewport's limits (a single value, applied both horizontally and/or vertically) This is used when the dialog box is stretched 100% horizontally and/or vertically and width and max_width are not set (when stretched horizontally) and height and max_height are not set (when stretched vertically).301 | This propery is also taken into account when using the position property.302 | Can be specified as a numeric value (which will be interpreted as a value in pixels) or as a percentage (of the viewport). 303 | |
304 |
max_height |
307 | mixed | 308 |0 | 309 |
310 | The maximum height of the dialog box. 311 | Can be specified as a numeric value (which will be interpreted as a value in pixels) or as a percentage (of the viewport). 312 | If this property is set to valid value greater than313 | |
314 |
max_width |
317 | mixed | 318 |450 | 319 |
320 | The maximum width of the dialog box. 321 | Can be specified as a numeric value (which will be interpreted as a value in pixels) or as a percentage (of the viewport). 322 | If this property is set to valid value greater than323 | |
324 |
message |
327 | string | 328 |329 | |
330 | The text (or HTML) to be displayed in the dialog box. 331 | See the source property on how to add content via AJAX, iFrames or from inline elements.
332 | |
333 |
modal |
336 | boolean | 337 |true | 338 |
339 | When set to true there will be a semitransparent backdrop behind the dialog box, preventing users from clicking the page's content.
340 | |
341 |
placeholder |
344 | string | 345 |"" (empty string) |
346 |
347 | When set to true there will be a semitransparent backdrop behind the dialog box, preventing users from clicking the page's content.348 | See also default_value property.
349 | |
350 |
position |
353 | mixed | 354 |'center' | 355 |
356 | Position of the dialog box. 357 | Can be either center (which would center the dialog box both horizontally and vertically), or an array with 2 elements, in the form of358 | // notice that everything is enclosed in quotes359 | ['horizontal_position +/- offset',360 | 'vertical_position +/- offset']361 | where 362 |
Positions are relative to the viewport (the area of the browser that is visible to the user) and
368 | the value of the
369 | Examples:370 | // position the dialog box in the top-left corner371 | // shifted 20 pixels inside372 | ['left + 20', 'top + 20']373 | // position the dialog box in the bottom-right corner374 | // shifted 20 pixels inside
375 | ['right - 20', 'bottom - 20']376 | // position the dialog box in center-top377 | // shifted 20 pixels down378 | ['center', 'top + 20']379 | Note that when the width of the viewport is less than 768 pixels, any arithmetics will be ignored (so, things like380 | |
381 |
prompt_rows |
384 | integer | 385 |1 | 386 |
387 | If the dialog box type is prompt, setting this property to a value higher than 1
388 | will change the input box to a textarea input having the specified number of rows.
389 | |
390 |
reposition_speed |
393 | integer | 394 |500 | 395 |396 | The duration (in milliseconds) of the animation used to reposition the dialog box when the browser window is resized. 397 | | 398 |
show_close_button |
401 | boolean | 402 |true | 403 |
404 | When set to true, a close button (the little "x") will be shown in the upper right corner of the dialog box.405 | If the dialog box has a title bar then the close button will be shown in the title bar, vertically centered and respecting the right padding. 406 | If the dialog box does not have a title bar then the close button will be shown in the upper right corner of the body of the dialog box, respecting the position related properties set in the stylesheet. 407 | |
408 |
source |
411 | mixed | 412 |false | 413 |
414 | Add content via AJAX, iFrames or from inline elements (together with the already applied events). 415 | This property can be any of the following: 416 |
|
445 |
title |
448 | string | 449 |"" (empty string, no title) |
450 | 451 | Title of the dialog box 452 | | 453 |
type |
456 | mixed | 457 |information | 458 |
459 | Dialog box type. 460 | Can be any of the following: 461 |
type property to false.470 | By default, the warning and question types have two buttons with the captions Ok and Cancel respectively, while the other types have a single button with the caption Ok.
471 | |
472 |
vcenter_short_message |
475 | boolean | 476 |477 | |
478 | Should messages shorter than the dialog's height be vertically centered? 479 | This property is ignored when480 | |
481 |
width |
484 | integer | 485 |0 (uses the value defined in the theme) |
486 |
487 | By default, the width of the dialog box is automatically computed in order to fit the content (but not exceed viewport. 488 | Can be specified as a numeric value (which will be interpreted as a value in pixels) or as a percentage (of the viewport). 489 | If490 | |
491 |
| Event | 501 |Description | 502 |
|---|---|
onOpen |
507 |
508 | Event fired after the dialog box is opened. 509 | The callback function receives as unique argument the dialog box, as a jQuery element. 510 | |
511 |
onBeforeClose |
514 |
515 | Event fired before the dialog box is closed. 516 | The main difference when compared to the 519 | The callback function receives as first argument the caption of the clicked button or boolean FALSE
520 | if the dialog box is closed by pressing the ESC key, by clicking the dialog box's x
521 | button, or by clicking the backdrop. The argument can also be boolean TRUE when the dialog box
522 | type is prompt and the ENTER key is pressed while inside the input box.523 | As second argument, the callback function receives the value entered in the input box - when the dialog box 524 | type is prompt and a button was clicked or the ENTER key was pressed while inside
525 | the input box, or undefined for any other case.526 | All this is important when expecting user input as you can say that you have user input only 527 | when the value of the first argument is boolean TRUEor the value it's the same as the label of
528 | the button considered as confirmation (i.e. "Ok"), and the value of the second argument is
529 | !== undefined.530 | See the buttons property for another way of handling user input.
531 | |
532 |
onClose |
535 |
536 | Event fired after the dialog box is closed. 537 | For executing functions before the closing of the dialog box, see the onBeforeClose 538 | event or the buttons property. 539 | For properly validating user input you might want to use the onBeforeClose event 540 | or the buttons property! 541 | The callback function receives as first argument the caption of the clicked button or boolean FALSE
542 | if the dialog box is closed by pressing the ESC key, by clicking the dialog box's x
543 | button, or by clicking the backdrop. The argument can also be boolean TRUE when the dialog box
544 | type is prompt and the ENTER key is pressed while inside the input box.545 | As second argument, the callback function receives the value entered in the input box - when the dialog box 546 | type is prompt and a button was clicked or the ENTER key was pressed while inside
547 | the input box, or undefined for any other case.548 | All this is important when expecting user input as you can say that you have user input only 549 | when the value of the first argument is boolean TRUEor the value it's the same as the label of
550 | the button considered as confirmation (i.e. "Ok"), and the value of the second argument is
551 | !== undefined.552 | See the buttons property or the onBeforeClose event for other ways of handling user input.
553 | |
554 |