Minitaur NPM | npm.io

minitaur

The ultimate, dependency-free, easy to use, JavaScript plugin for creating and managing modals.

Demo

Installation

Manual Download

Download dist/minitaur.min.js and place the following HTML in your page's head element:

<script type="text/javascript" src="dist/minitaur.min.js"></script>

CDN (Courtesy of jsDelivr)

Place the following HTML in your page's head element (check to make sure the version in the URL is the version you want):

<script type="text/javascript" src="https://cdn.jsdelivr.net/gh/kodie/minitaur@0.3.0/dist/minitaur.min.js"></script>

NPM

npm install minitaur --save

// ES6
import minitaur from 'minitaur'

// CommonJS
const minitaur = require('minitaur')

GPM

gpm install kodie/minitaur --save

Bower

bower install kodie/minitaur --save

Usage

The `minitaur` Function

Initiates minitaur.

Parameters

If the first parameter is set to an object, it will be used as the options parameter and the mount parameter will be set to the option object's mount value.

`mount`

Default: '.minitaur, [data-minitaur]'

The element(s) to turn into minitaur modals. Optional. Accepts String, NodeList, HTMLElement, or false. See the mount option for more information.

`options`

Default: (See Options section)

An object of options you can set to configure the modal(s). Optional. Accepts Object. See the Options section for more information.

Examples

window.addEventListener('load', function () {
  // Initialize minitaur with default options on all elements with the `minitaur` class or `data-minitaur` attribute
  minitaur()

  // Mount a different element as a modal
  minitaur('.modal')

  // Mount a custom element as a modal, and add a class to it
  minitaur(document.getElementById('my-element'), { class: 'alert' })

  // This does exactly the same as the above
  minitaur({
    class: ['alert'],
    mount: document.getElementById('my-element')
  })

  // Create a modal without using a pre-existing element, apply some custom styling, have it takeover and be opened, and close it after 5 seconds
  minitaur({
    afterOpen: function (modal) {
      setTimeout(function () {
        modal.minitaur.close()
      }, 5000)
    },
    content: '<p>Hi! I was created out of no where! But you can <a href="#" data-minitaur-close>close me</a> if you want.</p>',
    mount: false,
    opened: true,
    style: {
      backgroundColor: '#fff',
      padding: '10px'
    },
    takeover: true
  })

  // Mount an element, but store it in a variable and change it's content after initialization
  var myModal = minitaur('#alert')
  myModal.minitaur.set('content', '<span>This is an alert!</span>')

  // Let's change it's class and apply some styling too
  myModal.minitaur.set({
    class: 'viewed',
    style: {
      color: '#ff0000'
    }
  })

  // We can also get it after initialization and control it this way
  var alsoMyModal = document.getElementById('alert')
  alsoMyModal.minitaur.close()

  // We can do this as well
  minitaur.close(document.getElementById('alert'))
})

View the source of index.html for more examples.

Options

`afterClose`

Default: null

A function to run after the modal has been closed. Receives the modal instance as it's first parameter. Accepts a Function.

`afterInit`

Default: null

A function to run after the modal has been initiated. Receives the modal instance as it's first parameter. Accepts a Function.

`afterOpen`

Default: null

A function to run after the modal has been opened. Receives the modal instance as it's first parameter. Accepts a Function.

`anchor`

Default: null

The element that the modal should base it's size and position on. Accepts a String that will be passed to document.querySelector, an HTMLElement, or an Object containing x and/or y keys set to the before mentioned types to have the modal base it's horizontal and vertical positions on two different elements.

If this (or either of the x/y object keys) is set to 'viewport', the currently visible viewport will be used, also the modal's position will automatically be updated when the user scrolls the page.

If this (or either of the x/y object keys) is set to null, it will default to document.body unless the modal was opened via a trigger in which case it will default to the element that initiated the triggered event.

`backdropClass`

Default: 'minitaur-backdrop'

The class that is applied to the backdrop of a modal. Accepts a String. This is only used if the modal's takeover option is set to true.

`backdropClosingStyle`

Default: null

The style to apply to the backdrop of the modal while it is being closed. Accepts an Object of keys and values that will be applied to the style property of the backdrop element or null to not apply any styling. This is only used if the modal's takeover option is set to true.

`backdropOpeningStyle`

Default: null

The style to apply to the backdrop of the modal while it is being opened. Accepts an Object of keys and values that will be applied to the style property of the backdrop element or null to not apply any styling. This is only used if the modal's takeover option is set to true.

`backdropStyle`

Default: { backgroundColor: 'rgba(0, 0, 0, 0.5)' }

The style to apply to the backdrop of the modal. Accepts an Object of keys and values that will be applied to the style property of the backdrop element or null to not apply any styling. This is only used if the modal's takeover option is set to true.

`beforeClose`

Default: null

A function to run before the modal has been closed. Receives the modal instance as it's first parameter. Accepts a Function.

`beforeInit`

Default: null

A function to run before the modal has been initiated. Receives the modal instance as it's first parameter. Accepts a Function.

`beforeOpen`

Default: null

A function to run before the modal has been opened. Receives the modal instance as it's first parameter. Accepts a Function.

`breakpoints`

Default: null

An Object of options that are set depending on the browser window's width. Accepts an object containing numeric strings as keys (the browser width breakpoint in pixels) set to objects containing keys of other options to be set if the browser's width matches or exceeds the breakpoint. Accepts an Object.

Example:

minitaur({
  breakpoints: {
    '600': {
      content: 'Your browser window is at least 600 pixels wide'
    },
    '1200': {
      content: 'Your browser window is at least 1200 pixels wide'
    }
  }
})

`class`

Default: 'minitaur'

A class or classes to apply to the modal. Accepts a String or an Array of Strings.

`closeClass`

Default: 'closed'

The class that is applied to the modal after it has been closed. Accepts a String.

`closeDuration`

Default: 0

The number of milliseconds the modal should take to close. Useful for applying animations to the modal close event. Accepts a Number.

`closingClass`

Default: 'closing'

The class that is applied to the modal while it is closing. Accepts a String.

`closingStyle`

Default: null

The style to apply to the modal while it is being closed. Accepts an Object of keys and values that will be applied to the style property of the modal or null to not apply any styling.

`closeOnFocusOut`

Default: true

If set to true, the modal will be closed if any element outside of the modal is focused on or clicked. Accepts a Boolean.

`closeStyle`

Default: { display: 'none', visibility: 'hidden' }

The style to apply to the modal after it has been closed. Accepts an Object of keys and values that will be applied to the style property of the modal or null to not apply any styling.

`content`

Default: null

The HTML content to set for the modal. Can be left set to null if mounting a pre-existing element that has content already. Accepts a String or a Function that is passed the modal instance as it's first parameter and returns a String.

Any instances of {parameter} will be replaced with it's value in the parameters option.

`id`

Default: null

The id to set for the modal. If left set to null it will only set the id if one isn't already set on the mounted element, in which case the id will be set to minitaur-[modalCount]. Accepts a String.

This should really only be used when the mount option is set to false.

`mount`

Default: '.minitaur, [data-minitaur]'

An element to mount as the modal. Accepts a string that will be passed to document.querySelector, a NodeList, an HTMLElement, or false to create a new element.

`opened`

Default: false

Set to true to have the modal be opened after initialization. Accepts a Boolean.

`openClass`

Default: 'opened'

The class that is added to the modal after it has been opened. Accepts a String.

`openDuration`

Default: 0

The number of milliseconds the modal should take to open. Useful for applying animations to the modal open event. Accepts a Number.

`openingClass`

Default: 'opening'

The class that is applied to the modal while it is opening. Accepts a String.

`openingStyle`

Default: { display: 'block', visibility: 'visible' }

The style to apply to the modal while it is being opened. Accepts an Object of keys and values that will be applied to the style property of the modal or null to not apply any styling.

`openStyle`

Default: null

The style to apply to the modal after it has been opened. Accepts an Object of keys and values that will be applied to the style property of the modal or null to not apply any styling.

`overrides`

Default: null

An Object of options that are set for specific minitaur instances. Accepts an object containing strings as keys (a selector string that is passed to modal.matches()) set to objects containing keys of other options to be set if the modal matches the selector. Accepts an Object.

Example:

minitaur({
  overrides: {
    '.my-special-modal': {
      afterOpen: function () {
        alert('You opened my special modal.')
      }
    }
  }
})

`parameters`

Default: null

An Object containing keys that instances of {key} in the modal's HTML content should be replaced with it's value. Accepts an Object or null to not set any parameters.

`position`

Default: 'middle'

Possible horizontal position values: 'left', 'inner-left', 'middle', 'inner-right', 'right'

Possible vertical position values: 'top', 'inner-top', 'middle', 'inner-bottom', 'bottom'

The position of the modal based on the anchor element's size/position. Accepts a String with a single position value that will be used for both the horizontal and vertical position (ex. middle), a String with the vertical position first and horizontal position second separated by a space (ex. top right), or an Object containing x and/or y keys with their values set to their respective position value (ex. { x: 'right', y: 'top' }).

This option also accepts a Number, or a numeric String to manually set the pixel position based on the anchor element's size/position. A numeric String that ends with a percentage symbol (%) can also be used to set the position based on a percentage of the anchor element's size/position.

The modal will automatically reposition itself anytime the browser window is resized.

`respectAnchorSpacing`

Default: false

Set to true to have the anchor element's margin/padding calculated when setting the modal position. Accepts a Boolean.

The modal's own margin/padding is always respected.

`saveOptions`

Default: true

Set to false to have options passed to the minitaur.open and minitaur.close functions not save, making them only relevant that single instance of opening/closing the modal.

`saveParameters`

Default: true

Set to false to have options.parameters passed to the minitaur.open and minitaur.close functions not save, making them only relevant that single instance of opening/closing the modal.

`stayInBounds`

Default: true

If set to true, the modal will automatically reposition itself if the calculated position makes it go outside of document.body or out of the bounds of the anchor element (if one of the position option keys are set to 'inner-left', 'inner-right', 'inner-top', or 'inner-bottom', otherwise it's supposed to be out of the bounds of the anchor element), or if it overlaps the anchor element (if the anchor element is not document.body and one of the position option keys are set to 'left', 'right', 'top', or 'bottom' otherwise it's supposed to overlap). Accepts a Boolean.

`style`

Default: null

The style to apply to the modal. Accepts an Object of keys and values that will be applied to the style property of the modal or null to not apply any styling.

`takeover`

Default: false

Set to true to have a backdrop added behind the modal and disable page scroll while the modal is open. Accepts a Boolean.

A modal with this option enabled will have it's anchor option locked to 'viewport' and will have the data-minitaur-taking-over data attribute applied to it while it is open.

The backdrop element will also get the closingClass, openClass, and openingClass classes applied just like the modal. Additionally, it's id will be set to [modal-id]-backdrop and will get the data-minitaur-backdrop="#[modal-id]" data attribute applied to it.

The backdrop element will get it's zIndex style property set to 99998 and the modal's set to 99999 unless either one of these are overwritten by any style options.

Also, when a modal with this option enabled is opened, any other modals with this option enabled will be closed.

`template`

Default: null

The HTML to use as a template for the modal content. Any instances of {minitaur-content} will be replaced with the modal's content. Parameters from the parameters option can be used here too. Accepts a String or Function.

Example:

minitaur('.minitaur-modal', {
  template: '{minitaur-content}<button type="button" class="btn btn-primary" data-minitaur-close>Close Me</button>'
})

You can also define templates to use later by setting them in the minitaur.templates object and setting the template option to it's key rather than the HTML content.

Templates can be a function that is passed the modal as it's only parameter and returns a string.

Example:

minitaur.templates.myModal = '{minitaur-content}<button type="button" class="btn btn-primary" data-minitaur-close>Close Me</button>'

minitaur('.minitaur-modal', {
  template: 'myModal'
})

<div class="minitaur-modal">
  <p>Hi, I'm a minitaur modal. :)</p>
</div>

Will result in:

<div class="minitaur-modal minitaur minitaur-template-myModal">
  <div class="minitaur-content">
    <p>Hi, I'm a minitaur modal. :)</p>
  </div>
  <button type="button" class="btn btn-primary" data-minitaur-close>Close Me</button>
</div>

Tip: When using templates, your content gets wrapped in a div with the minitaur-content class. To use something other than a div, wrap the {minitaur-content} in an element of your choice with the minitaur-content class when setting the template content in the minitaur.templates object. For example: <span class="minitaur-content">{minitaur-content}</span>

`triggers`

Default: []

Possible action values: 'close', 'open', 'toggle'

Elements to add event listeners to that perform certain actions on the modal. Accepts a String/Array of Strings that will be passed to document.querySelector, or an Object/Array of Objects containing at the very least an elements key set to the before mentioned types. The action key can be set to one of the above action values (defaults to 'toggle'), and/or an events key can be set to a String/Array of Strings defining the type of event listener that should be used (defaults to 'click').

Examples:

minitaur({
  triggers: '.toggles-modal-when-clicked'
})

minitaur({
  triggers: [
    '.toggles-modal-when-clicked',
    '.also-toggles-modal-when-clicked',
    {
      action: 'open', // Defaults to "toggle"
      elements: '.opens-modal-when-hovered',
      events: 'mouseover' // Defaults to "click"
    },
    {
      action: 'close',
      elements: [
        '.closes-modal-when-unhovered-or-clicked',
        '.also-closes-modal-when-unhovered-or-clicked'
      ],
      events: [
        'mouseout',
        'click'
      ]
    }
  ]
})

Defaults Options

// All default options
minitaur({
  afterClose: null,
  afterInit: null,
  afterOpen: null,
  anchor: null,
  backdropClass: 'minitaur-backdrop',
  backdropClosingStyle: null,
  backdropOpeningStyle: null,
  backdropStyle: {
    backgroundColor: 'rgba(0, 0, 0, 0.5)'
  },
  beforeClose: null,
  beforeInit: null,
  beforeOpen: null,
  breakpoints: null,
  class: 'minitaur',
  closeClass: 'closed',
  closeDuration: 0,
  closingClass: 'closing',
  closingStyle: null,
  closeOnFocusOut: true,
  closeStyle: {
    display: 'none',
    visibility: 'hidden'
  },
  content: null,
  id: null,
  mount: '.minitaur, [data-minitaur]',
  opened: false,
  openClass: 'opened',
  openDuration: 0,
  openingClass: 'opening',
  openingStyle: {
    display: 'block',
    visibility: 'visible'
  },
  openStyle: null,
  overrides: null,
  parameters: null,
  position: 'middle',
  respectAnchorSpacing: false,
  saveOptions: true,
  saveParameters: true,
  stayInBounds: true,
  style: null,
  takeover: false,
  template: null,
  triggers: []
})

Modal Data Attributes

Most options above can be set by setting data-minitaur-* attributes on a pre-existing element that will be used in the mount option (ex: data-minitaur-anchor="#my-div", data-minitaur-respect-anchor-spacing="true"). You can also define breakpoints options as well (ex: data-minitaur-breakpoints-768-position-x="right").

Example

<div id="my-modal" class="minitaur" data-minitaur-anchor="#my-div" data-minitaur-respect-anchor-spacing="true" data-minitaur-breakpoints-768-position-x="right">
  <p>Hi, I'm a minitaur modal.</p>
</div>

Trigger Data Attributes

Trigger elements can be defined (in addition to using the triggers option) using the data-minitaur-close, data-minitaur-open, or data-minitaur-toggle data attributes set to a selector for the modal (ex. data-minitaur-open="#my-modal").

The value can be omitted from the trigger element if it's inside of a modal (ex. An element inside of a modal with the data-minitaur-close attribute not set to anything would close the modal that it is inside of).

Additionally, any modal data attributes as described in the above section can also be applied to trigger elements to set those options on the modal when the trigger element is triggered.

Example

<div id="my-modal" class="minitaur" data-minitaur-respect-anchor-spacing="true" data-minitaur-breakpoints-768-position-x="right">
  <p>Hi, I'm a minitaur modal. You can <a href="#" data-minitaur-close>close me</a> if you want.</p>
</div>

<button type="button" data-minitaur-toggle="#my-modal" data-minitaur-anchor="#my-div">Toggle Modal</button>

Global Methods

The global minitaur object has the following methods that can be used:

`close`

Closes a modal/modals. Accepts a String that will be passed to document.querySelector, a NodeList or an HTMLElement as the first parameter to specify the modal to close and optionally an Object containing options to set as the second parameter.

`kill`

Deinitializes a modal/modals. Accepts a String that will be passed to document.querySelector, a NodeList, or an HTMLElement as the first parameter to specify the modal to deinitialize and optionally a Boolean to decide to put the original element back the way it was before initialization as the second parameter (defaults to true).

`open`

Opens a modal/modals. Accepts a String that will be passed to document.querySelector, a NodeList, or an HTMLElement as the first parameter to specify the modal to open and optionally an Object containing options to set as the second parameter.

`set`

Sets options for a modal. Accepts a String that will be passed to document.querySelector, a NodeList, or an HTMLElement as the first parameter to specify the modal to set options for and an Object containing options to set as the second parameter. The second parameter also accepts a String set to an option key, in that case a third parameter should be defined to set that option's value.

`toggle`

Toggles a modal/modals' open state. Accepts a String that will be passed to document.querySelector, a NodeList, or an HTMLElement as the first parameter to specify the modal to open/close and optionally an Object containing options to set as the second parameter.

Examples

minitaur.close('#my-modal')

minitaur.kill('#my-modal', false)

minitaur.open('#my-modal', {
  afterOpen: function (modal) {
    console.log('My modal was opened')
  }
})

minitaur.set('#my-modal', {
  afterClose: function (modal) {
    console.log('My modal was closed')
  }
})

minitaur.toggle('#my-modal')

Modal Methods

The minitaur property is added to the modal with the following methods that can be used:

`close`

Closes the modal. Optionally accepts an Object containing options to set as the first parameter.

`kill`

Deinitializes the modal. Optionally accepts a Boolean to decide to put the original element back the way it was before initialization as the first parameter (defaults to true).

`open`

Opens the modal. Optionally accepts an Object containing options to set as the first parameter.

`set`

Sets options for the modal. Accepts an Object containing options to set as the first parameter. The first parameter also accepts a String set to an option key, in that case a second parameter should be defined to set that option's value.

`toggle`

Toggles the modal's open state. Optionally accepts an Object containing options to set as the first parameter.

Examples

modal.minitaur.close()

modal.minitaur.kill(false)

modal.minitaur.open({
  afterOpen: function (modal) {
    console.log('My modal was opened')
  }
})

modal.minitaur.set({
  afterClose: function (modal) {
    console.log('My modal was closed')
  }
})

modal.minitaur.toggle()

Modal Properties

The minitaur property is added to the modal with the following properties that can be used to detect the modal's current state:

`isOpen`

Is set to true if the modal is currently open, otherwise false.

Example

function checkIfMyModalIsOpen(modal) {
  if (modal.minitaur.isOpen) {
    console.log('My modal is open')
  } else {
    console.log('My modal is not open')
  }
}

Modal Events

The following events are triggered on a modal when an action is performed:

`close`

Fires when the modal is closed.

`open`

Fires when the modal is opened.

Examples

modal.addEventListener('open', function (e) {
  console.log('My modal was opened')
})

modal.addEventListener('close', function (e) {
  console.log('My modal was closed')
})

Styling

minitaur doesn't come with any default styling (except for the backdropStyle, closeStyle, and openingStyle option defaults) and doesn't require you to embed any CSS. However the modals can be very easily styled either by using CSS or by setting any of the style options available.

Examples

Basic Styling

.minitaur {
  background-color: #fff;
  border: 1px solid #000;
  border-radius: 5px;
  padding: 10px;
  text-align: center;
}

Animations

minitaur({
  closeDuration: 250
})

.minitaur {
  transition: opacity .25s ease, left .25s ease, top .25s ease;
}

.minitaur[data-minitaur-taking-over],
.minitaur-backdrop {
  transition: opacity .25s ease;
}

.minitaur.closing,
.minitaur.opening,
.minitaur-backdrop.closing,
.minitaur-backdrop.opening {
  opacity: 0
}

filebokz - A tiny, dependency-free, highly customizable and configurable, easy to use file input with some pretty sweet features.
growfield - A tiny, dependency-free JavaScript module for making textarea elements grow with their content.
hashjump - A tiny, dependency-free JavaScript module for handling anchor links and scrolling elements into view.
kloner - A tiny, dependency-free JavaScript module for cloning/repeating elements.
kolorfield - A tiny, dependency-free, color input field helper that utilizes the native color picker.
peekfield - A dependency-free, easy to use, JavaScript plugin for hiding and showing fields.

License

MIT. See the license file for more info.

alert close hidden hide html javascript js menu modal no-jquery open prompt toggle vanilla

@infinitebrahmanuniverse/nolb-minit @everything-registry/sub-chunk-2175

12 months ago

1 year ago

1 year ago

1 year ago

2 years ago

3 years ago

3 years ago

minitaur

Demo

Installation

Manual Download

CDN (Courtesy of jsDelivr)

NPM

GPM

Bower

Usage

The minitaur Function

Parameters

mount

options

Examples

Options

afterClose

afterInit

afterOpen

anchor

backdropClass

backdropClosingStyle

backdropOpeningStyle

backdropStyle

beforeClose

beforeInit

beforeOpen

breakpoints

class

closeClass

closeDuration

closingClass

closingStyle

closeOnFocusOut

closeStyle

content

id

mount

opened

openClass

openDuration

openingClass

openingStyle

openStyle

overrides

parameters

position

respectAnchorSpacing

saveOptions

saveParameters

stayInBounds

style

takeover

template

triggers

Defaults Options

Modal Data Attributes

Example

Trigger Data Attributes

Example

Global Methods

close

kill

open

set

toggle

Examples

Modal Methods

close

kill

open

set

toggle

Examples

Modal Properties

isOpen

Example

Modal Events

close

open

Examples

The `minitaur` Function

`mount`

`options`

`afterClose`

`afterInit`

`afterOpen`

`anchor`

`backdropClass`

`backdropClosingStyle`

`backdropOpeningStyle`

`backdropStyle`

`beforeClose`

`beforeInit`

`beforeOpen`

`breakpoints`

`class`

`closeClass`

`closeDuration`

`closingClass`

`closingStyle`

`closeOnFocusOut`

`closeStyle`

`content`

`id`

`mount`

`opened`

`openClass`

`openDuration`

`openingClass`

`openingStyle`

`openStyle`

`overrides`

`parameters`

`position`

`respectAnchorSpacing`

`saveOptions`

`saveParameters`

`stayInBounds`

`style`

`takeover`

`template`

`triggers`

`close`

`kill`

`open`

`set`

`toggle`

`close`

`kill`

`open`

`set`

`toggle`

`isOpen`

`close`

`open`