Fitzgerald

Fitzgerald (or just Fitz) is a minimalist modal window for the browser implemented in pure JavaScript and CSS.

Demo is available here and here (Vue).

Features

Customization with CSS variables
Accessibility (WAI-ARIA)
Focus trap
Scroll locking (with body-scroll-lock)
Animations and transitions (with animate.css, animista and etc.)
Plugin based architecture

Installation

Install the package using npm:

npm add fitzgerald

Or yarn:

yarn add fitzgerald

And add imports:

import createModal from 'fitzgerald'
import 'fitzgerald/src/style.css'
import 'fitzgerald/src/default-theme.css'

Also you can just include JS script and CSS file into your HTML page:

<link href="https://cdn.jsdelivr.net/gh/voronkovich/fitzgerald/dist/fitzgerald.min.css" rel="stylesheet">
<link href="https://cdn.jsdelivr.net/gh/voronkovich/fitzgerald/dist/fitzgerald-default-theme.min.css" rel="stylesheet">
<script src="https://cdn.jsdelivr.net/gh/voronkovich/fitzgerald/dist/fitzgerald.min.js"></script>

Usage example

Application:

import createModal from 'fitzgerald'
import 'fitzgerald/src/style.css'
import 'fitzgerald/src/default-theme.css'
const modal = createModal('Hey!')
modal.show()

Browser:

<script>
const modal = Fitz.createModal('Hey!')
modal.show()
</script>

Options

content string|HTMLElement

Sets modal’s content.

const modal = createModal({
    content: document.querySelector('#hello'),
})

const modal = createModal({
    content: `
        <h1>Lorem ipsum</h1>
        <p>Dolor sit amet...</p>
    `,
})

mount string|HTMLElement|DocumentFragment

Sets an element to which the modal will be mounted.

Default: document.body
```
const modal = createModal({
    content: 'Hey!',
    mount: '.modals',
})
```
id string

Sets an HTML attribute id for the modal.

class string|Object

Sets an HTML attribute class for the modal’s elements.

// Add class for the "root" element
const modal = createModal({
    class: 'sign-in' 
})

// TailwindCSS
const modal = createModal({
    class: {
        backdrop: 'bg-purple-500 opacity-75',
        content: `
            bg-white
            shadow-2xl
            rounded-xl
            p-6 mx-4 md:w-1/2 xl:w-1/3
            focus:outline-none
        `,
    }
})

position Object

Sets the modal’s position on the screen. By default modal positioned on the center of screen.
- vertical string
  
  Allowed values: top, center, bottom
- horizontal string
  
  Allowed values: left, center, right
```
const modal = createModal({
    position: {
        vertical: 'top',
        horizontal: 'right',
    }
})
```

style Object

Configures the modal’s style by adding CSS variables to it’s root element. All available CSS variables can be found at ./src/style.css and ./src/default-theme.css.

const modal = createModal({
    style: {
        // --fitz-backdrop-backdrop
        backdropBackground: '#eeaaee',
        // --fitz-width
        width: '50%',
    }
})

hide Object|string

Configures modal hiding behavior:

click string

Selector for elements which will be used to close modal by clicking on them.

Default: [data-fitz-hide]
escape boolean

Allows the user to close the modal by pressing ESC.

Default: true
backdrop boolean

Allows the user to close the modal by clicking the backdrop.

Default: true

const modal = createModal({
    content: `
        <button class="close-btn">Close</button>
        <h1>Lorem ipsum</h1>
        <p>Dolor sit amet...</p>
    `,
    hide: '.close-btn',
})

const modal = createModal({
    hide: {
        hide: '[data-close]',
        escape: false,   // Disable <ESC>
        backdrop: false, // Disable backdrop
    }
})

hash string

Allows to set a hash which will be used to show the modal.

<a href="#boo">Show modal</a>

const modal = createModal({
    content: 'Boo!',
    hash: '#boo', 
})

focus string|HTMLElement

Sets a selector for an element which will be focused after the modal is showed.

Default: [data-fitz-focus]

const modal = createModal({
    content: `
        <label>Enter your name:</label>
        <input type="text" name="name" />
    `,
    focus: 'input',
})

lockScroll string|HTMLElement

Sets a selector for an element which will be used as a target for body scroll locking.

Default: [data-fitz-lock-scroll]
aria Object

Configures ARIA:
- role string
  
  Modal role attribute.
  
  Default: dialog. See dialog role.
- label string
  
  A string value that labels the modal. See aria-label.
- labelledBy string
  
  Selector for element which will be used to label the modal. See aria-labelledby.
  
  Default: [data-fitz-aria-labelledby]
- describedBy string
  
  Selector for element which will be used to describe the modal. See aria-describedby.
  
  Default: [data-fitz-aria-describedby]
```
const modal = createModal({
    content: `
        <h2>Lorem ipsum</h2>
        <p>Dolor sit amet</p>
        <p>Consetetur sadipscing</p>
    `,
    aria: {
        role: 'alertdialog',
        labelledBy: 'h2',
        describedBy: 'p:first-child',
    },
})
```

animate Object

Allows to add CSS classes for arbitrary elements while the modal is being showing or hiding. You can use any library like animate.css or cssanimation.io.

To set an element which will be animated you can use keywords: root, backdrop, content or CSS selector.

```js
const modal = createModal({

animate: {
    root: {
        show: 'animate__animated animate__fadeIn',
        hide: 'animate__animated animate__fadeOut',
    },
    content: {
        show: 'animate__animated animate__bounceInDown',
        hide: 'animate__animated animate__fadeOutLeft',
    },
    '[type=submit]': {
        show: 'animate__animated animate__slow animate__bounceInRight',
    },
}

})

zIndex number|'auto'

Sets a z-index CSS property of modal’s root element. By default this value is calculated automatically to make modal appearing on the top of other page elements.
```
const modal = createModal({
    zIndex: 100, 
})
```

Instance API

Properties

root HTMLElement

Root element that wraps the backdrop and the modal’s content container.
backdrop HTMLElement

Backdrop element (overlay).
content HTMLElement

Container for the modal’s content.

You can use properties to interact with the modal DOM (attach event listeners, add nodes and etc.):

const modal = createModal({ /* Options */ })
modal.content.addEventListener('submit', (e) => {
    // Handle form submit
})

Methods

show() async

Shows modal.
hide() async

Hides modal.
destroy() async

Destroys modal.
setContent(content)

Sets the modal’s content.
on(event, callback)

Adds an event listener.
off(event, callback)

Removes an event listener.

const modal = createModal()
modal.setContent('This modal will be closed after 5 seconds.')
modal.show()
setTimeout(modal.hide, 5000)

Events

show:before

Occurs before showing the modal.
show

Occurs after the modal has been show.
show:after

Occurs after the modal has been show and all animations completed.
hide:before

Occurs before hiding the modal.
hide

Occurs after the modal has been hidden.
destroy

Occurs when the modal is being destroyed.

let counter = 0
const modal = createModal()
modal.on('show:before', () => {
    modal.setContent(`You've seen this modal ${++counter} times!`)
})