@chemaalfonso/modalizer

Modalizer

Modalizer is a JavaScript library for creating and managing modals in web applications. Written in TypeScript, it provides an easy way to create modal dialogs with customizable animations and styles.

✨ Features

• Native: Keep the native way using native dialog html element.
• Ease of Use: Implement modals in minutes with a simple and user-friendly API.
• Keep your rules: Modalizer only modalizes your content but you still have all its control.
• Dependency free: Modalizer use 0 dependencies.
• Quick Customization: Adapt the appearance of your modals to fit your project.
• Custom HTML Content: Effortlessly load any HTML content into your modals.
• Compatible animations: Compatible with Animate.css animations
• Customizable animations: Make your own and use custom animations
• Created in TypeScript: Modalizer is designed for use in TypeScript and JavaScript projects.
• Only 3.3kb minimified incuding styles
• Responsive: Native elements fits your needs on every screen
• Free use: MIT licensed

👀 Demo

View working example

⚙️ Installation

To use Modalizer in your project, you can:

Direct use from cdn

1. Basic styles:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@chemaalfonso/modalizer/dist/css/styles.min.css">

2. (Optional) Extra animations:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@chemaalfonso/modalizer/dist/css/animate.min.css">

3. Script:

    <script type="module">
        import { Modalizer } from 'https://cdn.jsdelivr.net/npm/@chemaalfonso/modalizer/dist/modalizer.min.js'
    </script>

Install via npm

npm i @chemaalfonso/modalizer

📝 Usage

Import into your project

1. Include style rules:

   // Basic css styles with fade in & out default animations
   import '@chemaalfonso/modalizer/dist/css/styles.css';
   
   // (Optional) Extra animate.css animations
   import '@chemaalfonso/modalizer/dist/css/animate.css';

2. Import & use script:

   Minimal example with HTML trigger

   import { Modalizer, Modalizable } from '@chemaalfonso/modalizer'
   
   // Define your modal content and trigger elements
   const element = document.querySelector('your-modal-content') as HTMLElement
   const trigger = document.querySelector('your-modal-trigger') as HTMLElement
   
   // Create a Modalizer instance
   const modalizer = new Modalizer({ element, trigger })

   Programatic modal invocation

   import { Modalizer, Modalizable } from '@chemaalfonso/modalizer'
   
   // Define your modal content
   const element = document.querySelector('your-modal-content') as HTMLElement
   
   // Create a Modalizer instance
   const modalizer = new Modalizer({ element })
   
   // Show modal
   modalizer.show()
   
   // Hide modal
   modalizer.hide()

🛠️ Configuration

Using config object

import { ModalizerConfig } from '@chemaalfonso/modalizer'

const config: ModalizerConfig = {
	animationIn: 'myInAnimation',
	animationOut: 'myOutAnimation',
	closeOnEscKeyPress: true,
	closer: myHtmlCloserElement,
	customClassName: 'my-class-name'
}

Config options reference

Property Name	Default Value	Description
animationIn	'modalizer-fadeIn'	The css class name with the animation for modal entry.
animationOut	'modalizer-fadeOut'	The css class name with the animation for modal exit.
closeOnEscKeyPress	true	Controls whether the modal is closed when pressing "Cancel."
closer	undefined	Optional: The HTML element to close the modal.
customClassName	undefined	Optional: Allows setting a CSS class to customize the modal.

🎨 Styling

Customizing styles

Include a custom class name

import { ModalizerConfig } from '@chemaalfonso/modalizer'

const config: ModalizerConfig = {
	customClassName: 'my-class-name',
	...
}

Apply your styles

.my-class-name {
	--modalizer-animation-duration: 0.4s;
	border-radius: 8px;
}

.my-class-name::backdrop {
	background: #6749e39f;
}

💃 Using animations

You can use any animation source. The only requeriment is a css class with the animation property and use it on the config object.

Using Animate.css animations

Include animate.css rules

import '@chemaalfonso/modalizer/dist/css/animate.css';

⚠️ Modalizer package includes a simplified animate.css version including only the in & out based animations.

Use Animate.css animation class names on config

import { ModalizerConfig } from '@chemaalfonso/modalizer'
import { MODALIZER_ANIMATE_ANIMATION_IN, MODALIZER_ANIMATE_ANIMATION_OUT } from '@chemaalfonso/modalizer/dist/animateAnimations'

const config: ModalizerConfig = {
	animationIn: MODALIZER_ANIMATE_ANIMATION_IN.LIGHTSPEED_IN_LEFT,
	animationOut: MODALIZER_ANIMATE_ANIMATION_OUT.FLIP_OUT_X
}

Creating custom animations

1. Create your custom animation and assign to css classes:

   .fadeIn {
   	animation: fadeIn 0.25s forwards;
   }
   
   .fadeOut {
   	animation: fadeOut 0.25s forwards;
   }
   
   @keyframes fadeIn {
   	0% {
   		opacity: 0;
   	}
   	100% {
   		opacity: 1;
   	}
   }
   
   @keyframes fadeOut {
   	0% {
   		opacity: 1;
   	}
   	100% {
   		opacity: 0;
   	}
   }

2. Use created css classes on config object:

   import { ModalizerConfig } from '@chemaalfonso/modalizer'
   
   const config: ModalizerConfig = {
   	animationIn: 'fadeIn',
   	animationOut: 'fadeOut'
   }

🔦 Linting

• npm run lint: Run linter
• npm run lint:fix: Fix lint issues

🔨 Dev

• npm run dev: Run tsc transpiler with watcher
• npm run dev:styles: Run styles compiler with watcher

📚 Build

• npm run build: Run project builder

📄 License

Modalizer is licensed under the MIT LICENSE. See the LICENSE file for details.

📱 Contact

If you have any questions or suggestions, feel free to open an issue.