# Modal

An overlay dialog that appears on top of the main content to focus user attention.

## Usage

Use standalone.

```svelte
<Modal {...props}>Content</Modal>
```

## Anatomy

The `class` attribute values represent part names. Other attributes represent their corresponding props.

```svelte
<dialog class="whole" {...rest} aria-label>
  {children}
</dialog>
```

## Props

| Name | Type | Default | Description |
|---|---|---|---|
| `children*` | `Snippet` | - | Modal content; receives the variant as its argument |
| `open` | `boolean` | `false` | Bindable open state |
| `closable` | `boolean` | `true` | Whether light dismiss is enabled; `false` blocks both backdrop-click and Escape |
| `duration` | `number` | `200` | Open/close animation timing in ms, published as the `--svs-duration` custom property |
| `cssvar` | `Record` | - | Renames the published animation-timing custom property; `cssvar.duration` makes the Modal read `--svs-duration` from a caller-named token |
| `ariaLabel` | `string` | - | Accessible label for the dialog |
| `element` | `HTMLDialogElement` | - | Bindable root element |
| `styling` | `SVSClass` | - | Styling override |
| `variant` | `SVSVariant` | `NEUTRAL` | Modal variant |
`*` required. Other `HTMLDialogAttributes` are passed to `<dialog>` via rest props; `class` is merged onto the root.

Modal is a native modal `<dialog>` opened with `showModal()`: focus is trapped and background content is inert while open, and page scroll is locked with `:root:has(dialog[open])`.

## Styling

Content renders directly inside the `<dialog>` (`whole` part), so background and padding belong on `whole`.
To learn more, see [Styling](/docs/styling).

### Variant Management

No automatic switching.

### Default Class Name

`svs-modal`

## Behavior

Open/close animation timing is published as `--svs-duration` for caller CSS; `cssvar.duration` renames it (caller then owns reduced-motion for that token).

## Accessibility

### ARIA Roles and Attributes

The component applies these automatically:

- Dialog (`whole` `<dialog>`): `aria-label` from the `ariaLabel` prop.

Provide an accessible name yourself because there is no built-in visible label. Pass `ariaLabel`, or pass `aria-labelledby` through the rest props. The managed `aria-label` attribute is omitted from `ModalProps` and cannot be passed as `aria-label`.

### Standards Basis

Modal is built on a native `<dialog>` opened with `showModal()`, so keyboard and assistive-technology support follows the browser standard for modal dialogs. See the [Concepts standards-first guidance](/docs/concepts) for the library's approach. When `closable` is `false`, the component prevents the native Escape light-dismiss; note that a modal dialog that cannot be dismissed with Escape runs contrary to the WAI-ARIA authoring-practices recommendation for dialogs, so use it deliberately.

## Exports

### Types

```ts
interface ModalProps extends Omit<HTMLDialogAttributes, "children" | "style" | "aria-label"> {
  children: Snippet<[string]>; // Snippet<[variant]>
  open?: boolean; // bindable (false)
  closable?: boolean; // (true)
  duration?: number; // (200)
  cssvar?: Partial<Record<ModalCssVar, string>>;
  ariaLabel?: string;
  element?: HTMLDialogElement; // bindable
  styling?: SVSClass;
  variant?: SVSVariant; // (VARIANT.NEUTRAL)
  // other HTMLDialogAttributes are passed to <dialog> via ...rest; `class` is merged onto root
  // style is component-owned (omitted)
}
type ModalReqdProps = "children";
type ModalBindProps = "open" | "element";
type ModalCssVar = "duration";
```

### Others

No additional exports are available.

## Examples

The example code uses Tailwind CSS along with `SVSClass`.

### Basic

**Code**

```svelte src=ModalBasic.svelte
<script lang="ts">
  import { Modal } from "svseeds";

  const id = "zmodal1";
  const styling = {
    whole: "rounded-md p-4 backdrop:bg-black/30 dark:backdrop:bg-white/30",
  };
  const myProps = {
    id,
    styling,
  };
</script>

<!--
  Note: When using the `open` prop, avoid the command attribute for state control,
        as the `toggle` event for dialog elements support varies across browsers.
-->
<button class="px-2 rounded-md border text-center cursor-pointer" commandfor={id} command="show-modal">Open Modal</button>
<Modal {...myProps}>Hello!!</Modal>
```
### With Interactive Variant

**Code**

```svelte src=ModalPract.svelte
<script lang="ts">
  import { Modal } from "svseeds";

  let { variant = $bindable() } = $props();
  let open = $state(false);
  const variantStyle = {
    neutral: "border-transparent",
    active: "border-teal-500",
    inactive: "border-red-500",
    blue: "border-blue-500",
    yellow: "border-yellow-500",
    sky: "border-sky-500",
  };
  const styling = {
    whole: {
      base: "w-fit rounded-sm border p-4 text-white backdrop:bg-black/30 dark:bg-black dark:backdrop:bg-white/30",
      ...variantStyle,
    },
  };
  const myProps = {
    styling,
  };
</script>

<button type="button" class="px-2 rounded-md border text-center cursor-pointer" onclick={() => (open = true)}>Open Modal</button>

<Modal bind:open {variant} {...myProps}>
  <div class="text-lg font-medium">Notifications</div>
  <p>New features are available!</p>
  <div class="flex justify-end">
    <button type="button" class="mt-4 px-2 w-20 bg-teal-600 rounded-sm text-center cursor-pointer" onclick={() => (open = false)}>OK</button
    >
  </div>
</Modal>
```