Modal

A dialog overlay that displays content in a floating container above the page with configurable animations, positions, and sizes.

Import

tsx

import { Modal } from "asheeui";

Usage

tsx

"use client";

import { Button, Modal } from "asheeui";
import { useState } from "react";

export default function Basic() {
	const [isOpen, setIsOpen] = useState(false);

	return (
		<div className="flex flex-col items-center gap-4 ">
			<Button onClick={() => setIsOpen(true)}>Open Modal</Button>

			<Modal isOpen={isOpen} onClose={() => setIsOpen(false)}>
				<div className="flex flex-col p-2">
					<header className="flex items-center justify-between border-b pb-4">
						<h2 className="text-lg font-semibold">Modal Title</h2>
						<button
							type="button"
							aria-label="Close modal"
							onClick={() => setIsOpen(false)}
							className="rounded-full p-1.5 transition-colors hover:hover:bg-foreground/10"
						>
							<CloseIcon />
						</button>
					</header>
					<div className="py-4">
						<p className="text-sm text-foreground">
							Basic modal with default settings.
						</p>
					</div>
				</div>
			</Modal>
		</div>
	);
}

function CloseIcon() {
	return (
		<svg
			xmlns="http://www.w3.org/2000/svg"
			width="18"
			height="18"
			viewBox="0 0 24 24"
			fill="none"
			stroke="currentColor"
			strokeWidth="2"
			strokeLinecap="round"
			strokeLinejoin="round"
			aria-hidden="true"
		>
			<line x1="18" y1="6" x2="6" y2="18" />
			<line x1="6" y1="6" x2="18" y2="18" />
		</svg>
	);
}

Examples

Size variants

Radius

Position

Animation presets

Custom width and height

Backdrop behavior

ESC key behavior

Custom overlay

Props

Prop	Type	Default	Description
`isOpen`	`boolean`	None	Controls modal visibility (required)
`onClose`	`() => void`	None	Callback when modal closes
`children`	`ReactNode`	None	Modal content (required)
`size`	`"sm" \| "md" \| "lg" \| "xl" \| "full"`	`"md"`*	Size scale
`position`	`"center" \| "top" \| "bottom"`	`"center"`*	Vertical placement
`radius`	`"none" \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| "full"`	`"lg"`*	Corner rounding
`animated`	`boolean`	`true`*	Enable/disable animations
`width`	`string`	None	Custom width override
`height`	`string`	None	Custom height override
`closeOnBackdropClick`	`boolean`	`true`*	Close when clicking backdrop
`closeOnEscape`	`boolean`	`true`*	Close when pressing ESC key
`overlayClassName`	`string`	None	Extra classes for overlay
`contentClassName`	`string`	None	Extra classes for content container
`className`	`string`	None	Extra classes for modal container

* Falls back through Global Configuration if not set. See below.

Global Configuration

Modal reads defaults from four places, in this order of precedence:

Instance prop: set directly on <Modal />
Component config: components.modal in your ashee.config
Theme default: defaultRadius in your ashee.config
Built-in fallback: component's internal default values

Component config

// ashee.config.ts
import type { ExternalConfig } from "asheeui";

export const config: ExternalConfig = {
  components: {
    modal: {
      size: "md",
      position: "center",
      radius: "lg",
      animated: true,
      closeOnBackdropClick: true,
      closeOnEscape: true,
    },
  },
};

Built-in fallbacks

{
  size: "md",
  position: "center",
  radius: "lg",
  animated: true,
  closeOnBackdropClick: true,
  closeOnEscape: true,
}

Accessibility

Renders a native dialog role with aria-modal="true"
Automatically locks body scroll when open
Focus management with focus trapping
ESC key support for closing (configurable)
Backdrop click support for closing (configurable)
Implements focus-visible outlines for keyboard navigation

Notes

Body Scroll Lock: When the modal is open, scrolling on the body is automatically disabled to prevent background scrolling.
Animation: The modal uses pop animation by default with a 200ms duration. Disable with animated={false}.
Custom Sizing: Use width and height props to override the default size-based values.
Position: The top position places the modal near the top with margin, while bottom places it near the bottom.
Focus Management: Focus is automatically trapped inside the modal for accessibility.
Backdrop: The backdrop overlay is a button element that can be clicked to close the modal when closeOnBackdropClick is enabled.