Modal

Import

import { Modal } from "@darkcode-ui/react";

Usage

"use client";

import {Button, Modal} from "@darkcode-ui/react";
import {Rocket} from "@gravity-ui/icons";

Anatomy

Import the Modal component and access all parts using dot notation.

import {Modal, Button} from "@darkcode-ui/react";

export default () => (
  <Modal>
    <Button>Open Modal</Button>
    <Modal.Backdrop>
      <Modal.Container>
        <Modal.Dialog>
          <Modal.CloseTrigger /> {/* Optional: Close button */}
          <Modal.Header>
            <Modal.Icon /> {/* Optional: Icon */}
            <Modal.Heading />
          </Modal.Header>
          <Modal.Body />
          <Modal.Footer />
        </Modal.Dialog>
      </Modal.Container>
    </Modal.Backdrop>
  </Modal>
);

Placement

"use client";

import {Button, Modal} from "@darkcode-ui/react";
import {Rocket} from "@gravity-ui/icons";

Backdrop Variants

"use client";

import {Button, Modal} from "@darkcode-ui/react";
import {Rocket} from "@gravity-ui/icons";

Sizes

"use client";

import {Button, Modal} from "@darkcode-ui/react";
import {Rocket} from "@gravity-ui/icons";

Custom Backdrop

"use client";

import {Button, Modal} from "@darkcode-ui/react";
import {Sparkles} from "@gravity-ui/icons";

Dismiss Behavior

"use client";

import {Button, Modal} from "@darkcode-ui/react";
import {CircleInfo} from "@gravity-ui/icons";

Close Methods

"use client";

import {Button, Modal} from "@darkcode-ui/react";
import {CircleCheck, CircleInfo} from "@gravity-ui/icons";

Scroll Behavior

"use client";

import {Button, Label, Modal, Radio, RadioGroup} from "@darkcode-ui/react";
import {useState} from "react";

Controlled State

"use client";

import {Button, Modal, useOverlayState} from "@darkcode-ui/react";
import {CircleCheck} from "@gravity-ui/icons";
import React from "react";

With Form

"use client";

import {Button, Input, Label, Modal, Surface, TextField} from "@darkcode-ui/react";
import {Envelope} from "@gravity-ui/icons";

Custom Trigger

"use client";

import {Button, Modal} from "@darkcode-ui/react";
import {Gear} from "@gravity-ui/icons";

Custom Animations

"use client";

import {Button, Modal} from "@darkcode-ui/react";
import {ArrowUpFromLine, Sparkles} from "@gravity-ui/icons";
import React from "react";

Custom Portal

"use client";

import {Button, Modal} from "@darkcode-ui/react";
import {useCallback, useRef, useState} from "react";

Styling

Passing Tailwind CSS classes

import {Modal, Button} from "@darkcode-ui/react";

function CustomModal() {
  return (
    <Modal>
      <Button>Open Modal</Button>
      <Modal.Backdrop className="bg-black/80">
        <Modal.Container className="items-start pt-20">
          <Modal.Dialog className="bg-linear-to-br from-purple-500 to-pink-500 text-white">
            <Modal.CloseTrigger />
            <Modal.Header>
              <Modal.Heading>Custom Styled Modal</Modal.Heading>
            </Modal.Header>
            <Modal.Body>
              <p>This modal has custom styling applied via Tailwind classes</p>
            </Modal.Body>
            <Modal.Footer>
              <Button slot="close">Close</Button>
            </Modal.Footer>
          </Modal.Dialog>
        </Modal.Container>
      </Modal.Backdrop>
    </Modal>
  );
}

Customizing the component classes

To customize the Modal component classes, you can use the @layer components directive.

Learn more.

@layer components {
  .modal__backdrop {
    @apply bg-gradient-to-br from-black/50 to-black/70;
  }

  .modal__dialog {
    @apply rounded-2xl border border-white/10 shadow-2xl;
  }

  .modal__header {
    @apply text-center;
  }

  .modal__close-trigger {
    @apply rounded-full bg-white/10 hover:bg-white/20;
  }
}

DarkCode UI follows the BEM methodology to ensure component variants and states are reusable and easy to customize.

CSS Classes

The Modal component uses these CSS classes (View source styles):

Base Classes

• .modal__trigger - Trigger element that opens the modal
• .modal__backdrop - Overlay backdrop behind the modal
• .modal__container - Positioning wrapper with placement support
• .modal__dialog - Modal content container
• .modal__header - Header section for titles and icons
• .modal__body - Main content area
• .modal__footer - Footer section for actions
• .modal__close-trigger - Close button element

Backdrop Variants

• .modal__backdrop--opaque - Opaque colored backdrop (default)
• .modal__backdrop--blur - Blurred backdrop with glass effect
• .modal__backdrop--transparent - Transparent backdrop (no overlay)

Scroll Variants

• .modal__container--scroll-outside - Enables scrolling the entire modal
• .modal__dialog--scroll-inside - Constrains modal height for body scrolling
• .modal__body--scroll-inside - Makes only the body scrollable
• .modal__body--scroll-outside - Allows full-page scrolling

Interactive States

The component supports these interactive states:

• Focus: :focus-visible or [data-focus-visible="true"] - Applied to trigger, dialog, and close button
• Hover: :hover or [data-hovered="true"] - Applied to close button on hover
• Active: :active or [data-pressed="true"] - Applied to close button when pressed
• Entering: [data-entering] - Applied during modal opening animation
• Exiting: [data-exiting] - Applied during modal closing animation
• Placement: [data-placement="*"] - Applied based on modal position (auto, top, center, bottom)

API Reference

Modal

Modal.Trigger

Modal.Backdrop

Modal.Container

Modal.Dialog

Modal.Header

Modal.Body

Modal.Footer

Modal.CloseTrigger

useOverlayState Hook

import {useOverlayState} from "@darkcode-ui/react";

const state = useOverlayState({
  defaultOpen: false,
  onOpenChange: (isOpen) => console.log(isOpen),
});

state.isOpen; // Current state
state.open(); // Open modal
state.close(); // Close modal
state.toggle(); // Toggle state
state.setOpen(); // Set state directly

Accessibility

Implements WAI-ARIA Dialog pattern:

• Focus trap: Focus locked within modal
• Keyboard: ESC closes (when enabled), Tab cycles elements
• Screen readers: Proper ARIA attributes
• Scroll lock: Body scroll disabled when open