@versini/ui-dialog

A lightweight and accessible React dialog component built with TypeScript and TailwindCSS.

The Dialog component is a minimal modal container leveraging the native HTML <dialog> element. It provides an efficient alternative to heavier modal libraries with built-in accessibility, focus management, and animation support.

Table of Contents

• Features
• Installation
• Usage
• API

Features

• ⚡ Lightweight: Uses native HTML <dialog> element for minimal overhead
• ♿ Accessible: WCAG compliant with built-in focus management and ARIA support
• 🎨 Flexible Layout: Two layout kinds (panel and messagebox) to suit different use cases
• ✨ Animated: Optional slide or fade animations for opening/closing
• 🎭 Theme Support: Multiple border modes and blur effects
• 🌲 Tree-shakeable: Optimized for bundle size
• 🔧 TypeScript: Fully typed with comprehensive prop definitions
• 🎯 Focus Management: Intelligent initial focus handling with customizable options

Installation

npm install @versini/ui-dialog

Note: This component requires TailwindCSS and the @versini/ui-styles plugin for proper styling. See the installation documentation for complete setup instructions.

Usage

Basic Dialog

import { useState } from "react";
import { Dialog } from "@versini/ui-dialog";

function App() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <button onClick={() => setOpen(true)}>Open Dialog</button>
      <Dialog
        open={open}
        onOpenChange={setOpen}
        title="Welcome"
      >
        <p>This is a simple dialog content.</p>
      </Dialog>
    </>
  );
}

Dialog with Footer

import { useState } from "react";
import { Dialog } from "@versini/ui-dialog";
import { Button } from "@versini/ui-button";

function App() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <button onClick={() => setOpen(true)}>Open Dialog</button>
      <Dialog
        open={open}
        onOpenChange={setOpen}
        title="Confirm Action"
        footer={
          <div className="flex gap-2 justify-end">
            <Button onClick={() => setOpen(false)}>Cancel</Button>
            <Button variant="primary" onClick={() => setOpen(false)}>Confirm</Button>
          </div>
        }
      >
        <p>Are you sure you want to proceed?</p>
      </Dialog>
    </>
  );
}

Dialog with Animation

import { useState } from "react";
import { Dialog } from "@versini/ui-dialog";

function App() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <button onClick={() => setOpen(true)}>Open Dialog</button>
      <Dialog
        open={open}
        onOpenChange={setOpen}
        title="Animated Dialog"
        animation
        animationType="fade"
      >
        <p>This dialog slides in with a fade animation.</p>
      </Dialog>
    </>
  );
}

Messagebox Layout

import { useState } from "react";
import { Dialog } from "@versini/ui-dialog";

function App() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <button onClick={() => setOpen(true)}>Open Messagebox</button>
      <Dialog
        open={open}
        onOpenChange={setOpen}
        title="Important Message"
        kind="messagebox"
      >
        <p>This uses the messagebox layout for centered, compact dialogs.</p>
      </Dialog>
    </>
  );
}

Custom Focus Management

import { useRef, useState } from "react";
import { Dialog } from "@versini/ui-dialog";

function App() {
  const [open, setOpen] = useState(false);
  const submitButtonRef = useRef<HTMLButtonElement>(null);

  return (
    <>
      <button onClick={() => setOpen(true)}>Open Dialog</button>
      <Dialog
        open={open}
        onOpenChange={setOpen}
        title="Focus Management"
        initialFocus={submitButtonRef}
      >
        <input type="text" placeholder="This is skipped" />
        <button ref={submitButtonRef}>This gets focus</button>
      </Dialog>
    </>
  );
}

API

Dialog Props

| Prop | Type | Default | Description | | ----------------- | ----------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------- | | open | boolean | - | Controls whether the dialog is visible | | onOpenChange | (open: boolean) => void | - | Callback fired when the dialog should open or close | | title | string | - | The title displayed in the dialog header | | children | React.ReactNode | - | The main content of the dialog | | footer | React.ReactNode | - | Optional footer content, typically containing action buttons | | kind | "panel" \| "messagebox" | "panel" | Layout type (panel for general content, messagebox for centered alerts) | | borderMode | "dark" \| "medium" \| "light" | "light" | Border styling mode | | animation | boolean | false | Enable animations for opening/closing | | animationType | "slide" \| "fade" | "slide" | Animation style (only used when animation is true) | | maxWidth | "small" \| "medium" \| "large" | "medium" | Maximum width for panel layout (does not affect messagebox) | | maxHeight | "small" \| "medium" \| "large" | - | Maximum height (large for panel, small for messagebox) | | blurEffect | "none" \| "small" \| "medium" \| "large" | "none" | Blur effect for header and footer backgrounds | | initialFocus | number \| React.RefObject<HTMLElement \| null> \| -1 | 0 | Element to focus on open: number = tabbable index, ref = element, -1 = no focus | | className | string | - | CSS class(es) to add to the dialog element |

Examples

Responsive Dialog

import { useState } from "react";
import { Dialog } from "@versini/ui-dialog";

function App() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <button onClick={() => setOpen(true)}>Open Dialog</button>
      <Dialog
        open={open}
        onOpenChange={setOpen}
        title="Responsive Dialog"
        maxWidth="large"
        maxHeight="medium"
      >
        <p>This dialog adapts to different screen sizes.</p>
      </Dialog>
    </>
  );
}

Dialog with Blur Effect

import { useState } from "react";
import { Dialog } from "@versini/ui-dialog";

function App() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <button onClick={() => setOpen(true)}>Open Dialog</button>
      <Dialog
        open={open}
        onOpenChange={setOpen}
        title="Dialog with Blur"
        blurEffect="medium"
      >
        <p>The header and footer have a blur effect applied.</p>
      </Dialog>
    </>
  );
}

Custom Styling

import { useState } from "react";
import { Dialog } from "@versini/ui-dialog";

function App() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <button onClick={() => setOpen(true)}>Open Dialog</button>
      <Dialog
        open={open}
        onOpenChange={setOpen}
        title="Styled Dialog"
        className="rounded-lg shadow-2xl"
        borderMode="dark"
      >
        <p>Custom styling applied to the dialog.</p>
      </Dialog>
    </>
  );
}

Accessibility

import { useState } from "react";
import { Dialog } from "@versini/ui-dialog";

function App() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <button onClick={() => setOpen(true)}>Open Dialog</button>
      <Dialog
        open={open}
        onOpenChange={setOpen}
        title="Accessible Dialog"
        initialFocus={0}
      >
        <p>The first interactive element receives focus automatically.</p>
        <input type="text" placeholder="Focus is managed for you" />
      </Dialog>
    </>
  );
}