Skip to main content

Getting Started

Introduction​

The @codeleap/modals library is a modern, powerful solution for creating and managing React modals with an elegant, fluent API. It provides a declarative approach to modal management, allowing you to create everything from simple alerts to complex form dialogs with built-in request/response patterns.

The first decision is not conceptual, it is architectural: check the app package.json.

  • if the app already depends on @codeleap/modals, keep modal work aligned with this package
  • if the app depends on @codeleap/portals, use portals instead

Key Features​

  • Fluent API Design - Chain methods for clean, readable modal definitions
  • Request/Response System - Modals can return data using async/await patterns
  • TypeScript Native - Full type safety for parameters and return values
  • Automatic Stack Management - Multiple modals work seamlessly together
  • React Hooks Integration - Control modal state with familiar React patterns
  • Global Configuration - Customize wrapper components and default behaviors
  • Async Parameters - Load data before displaying modals
  • Independent Rendering - Flexible rendering options for advanced use cases

Installing the Library​

Install @codeleap/modals using Bun:

bun add @codeleap/modals

Quick Setup​

1. Configure the Global Wrapper (once)​

Import and configure at the root of your application:

import { Modal } from '@codeleap/modals'
import { MyModalWrapper } from './components/MyModalWrapper'

// Set your custom wrapper component
Modal.WrapperComponent = MyModalWrapper

This setup is required. Modal.GlobalOutlet will not be enough on its own if the wrapper component was never assigned.

2. Add the Global Outlet​

Add the modal outlet to your main App component:

import { Modal } from '@codeleap/modals'

function App() {
  return (
    <div>
      {/* Your application content */}
      <Routes>
        {/* Your routes */}
      </Routes>
      
      {/* Add this at the end - renders all modals */}
      <Modal.GlobalOutlet />
    </div>
  )
}

This setup is also required for normal registered modals. The wrapper renders the shell, and the global outlet renders the modal instances into the tree.

3. Create Your First Modal​

The modal instance content will always be rendered inside this WrapperComponent

import { modal } from '@codeleap/modals'

const HelloModal = modal()
  .content(() => (
    <div>
      <h2>Hello World!</h2>
      <p>Your first modal is working!</p>
    </div>
  ))

// Open it anywhere in your app
HelloModal.open()

That's it! Your modal system is now set up and ready to use. The modal will appear with your custom wrapper styling and can be opened from anywhere in your application.

When to use this package​

  • Use @codeleap/modals when the app package.json already includes it.
  • Use @codeleap/portals when the app package.json includes portals instead.