---
metaTitle: Modal component | AwesCode UI
meta:
  - name: description
    content: The <AwModal /> component is used to render Modal - UI Vue component for AwesCode UI.
title: Modal
---

# AwModal

**Category:** Organism | **Import:** Dynamic

The `AwModal` component is a flexible modal dialog system that supports multiple themes, URL-based state management, and customizable layouts. It provides accessibility features, body scroll locking, and keyboard navigation.

## Overview

`AwModal` provides a comprehensive modal solution with:
- Multiple themes: `default`, `fullscreen`, `bottom`, `aside`, `overlay-aside`, `overlay-aside-medium`, `overlay-aside-large`
- URL query parameter integration for state management
- Body scroll locking (configurable per theme)
- Keyboard support (ESC to close)
- Focus management and accessibility
- Customizable header, content, and footer sections
- Event bus integration for programmatic control

## Usage

### Basic Example

```markup
<template>
    <AwButton @click="$root.$emit('modal::form:open')">
        Show Modal
    </AwButton>
    
    <AwModal title="Form Modal" name="form">
        <AwInput label="Name" name="name" />
        <AwButton @click="$root.$emit('modal::form:close')">
            Close
        </AwButton>
    </AwModal>
</template>
```

### With Subtitle and Buttons Slot

```markup
<AwModal title="Modal Title" name="example">
    <template #subtitle>Subtitle text</template>
    
    <AwInput label="Name" name="name" />
    
    <template #buttons>
        <AwButton size="lg" class="flex-1">Save</AwButton>
        <AwButton size="lg" color="default" theme="ghost" class="flex-1">
            Cancel
        </AwButton>
    </template>
</AwModal>
```

### Different Themes

```markup
<!-- Default modal -->
<AwModal title="Default" name="default" theme="default" />

<!-- Fullscreen modal -->
<AwModal title="Fullscreen" name="fullscreen" theme="fullscreen" />

<!-- Bottom sheet -->
<AwModal title="Bottom" name="bottom" theme="bottom" :param="false" />

<!-- Aside drawer -->
<AwModal title="Aside" name="aside" theme="aside" param="drawer" />
```

### Custom Header

```markup
<AwModal title="Custom Header" name="custom">
    <template #before-title>
        <AwIcon name="awesio/info-circle" />
    </template>
    
    <template #after-title>
        <AwBadge text="New" />
    </template>
    
    <template #header="{ title, close }">
        <div class="custom-header">
            <h2>{{ title }}</h2>
            <AwButton @click="close">×</AwButton>
        </div>
    </template>
</AwModal>
```

### Without URL Parameters

```markup
<AwModal 
    title="Local Modal" 
    name="local" 
    :param="false"
    ref="localModal"
>
    <AwButton @click="$refs.localModal.open()">Open</AwButton>
    <AwButton @click="$refs.localModal.close()">Close</AwButton>
</AwModal>
```

### Not Closable Modal

```markup
<AwModal 
    title="Not Closable" 
    name="not-closable"
    not-closing
>
    <AwInput label="Name" name="name" />
    <AwButton @click="$refs.modal.close()">Close Programmatically</AwButton>
</AwModal>
```

## API

### Props

| Name | Description | Type | Required | Default |
|------|-------------|------|----------|---------|
| title | Modal title text | `String` | `false` | `''` |
| name | Unique modal identifier | `String` | `false` | `'modal-{id}'` |
| param | Query parameter name for URL state (or `false` to disable) | `String` / `Boolean` | `false` | `'modal'` |
| theme | Modal theme/style | `String` | `false` | `'default'` |
| stay | Keep content mounted when closed | `Boolean` | `false` | `false` |
| bgClickClose | Close modal when clicking background | `Boolean` | `false` | `true` |
| notClosing | Prevent modal from being closed | `Boolean` | `false` | `false` |
| disableScroll | Disable body scrolling when open | `Boolean` | `false` | Auto (based on theme) |
| className | Custom CSS class | `String` | `false` | `'modal'` |

**Theme Options:**
- `default` - Standard centered modal
- `fullscreen` - Full screen modal
- `bottom` - Bottom sheet style
- `aside` - Side drawer
- `overlay-aside` - Overlay aside drawer
- `overlay-aside-medium` - Medium overlay aside
- `overlay-aside-large` - Large overlay aside

**Disable Scroll Defaults:**
Body scrolling is automatically disabled for: `default`, `fullscreen`, `bottom`, `overlay-aside`, `overlay-aside-medium`, `overlay-aside-large`

### Slots

| Name | Description | Props | Default Slot Content |
|------|-------------|-------|---------------------|
| default | Main modal content | `{ closeModal }` | - |
| subtitle | Subtitle text below title | - | - |
| buttons | Footer buttons area | - | - |
| header | Custom header (replaces default) | `{ title, close }` | Default header with title and close button |
| before-title | Content before title in header | - | - |
| after-title | Content after title in header (replaces close button if provided) | - | - |

### Events

| Name | Payload | Description |
|------|---------|-------------|
| opened | - | Emitted when modal finishes opening animation |
| closed | - | Emitted when modal finishes closing animation |
| before-open | - | Emitted before modal opens |
| before-close | `{ preventClose() }` | Emitted before modal closes (can prevent closing) |
| after-close | - | Emitted after modal closes |

### Methods

| Name | Parameters | Description |
|------|------------|-------------|
| open | - | Opens the modal |
| close | - | Closes the modal |

### Event Bus

The modal can be controlled via event bus:

```javascript
// Open modal
this.$root.$emit(`modal::${name}:open`)

// Close modal
this.$root.$emit(`modal::${name}:close`)

// Listen for close
this.$root.$on(`modal::${name}:closed`, () => {
  // Modal closed
})
```

### Config Options

The component uses default configuration from `@AwConfig`. You can override these defaults in your project's `awes.config.js`:

```javascript
export default {
  AwModal: {
    baseClass: 'aw-modal',
    stay: false,
    bgClickClose: true,
    eventBus: this.$root  // Event bus instance for modal events
  }
}
```

**Default Config:**
- `baseClass`: `'aw-modal'`
- `stay`: `false`
- `bgClickClose`: `true`
- `eventBus`: `this.$root` (can be customized)

## Related Components

- `AwButton` - Button component for modal actions
- `AwInput` - Input component for forms in modals
- `AwPage` - Page component that may contain modals

## Notes

- **Import Method:** Dynamic - Component is loaded on-demand as an organism
- When `param` is set, modal state is managed via URL query parameters
- When `param` is `false`, modal uses local state (`localOpened`)
- Modal automatically manages focus (focuses header on open, restores focus on close)
- ESC key closes modal (unless `notClosing` is true)
- Body scroll is locked when modal is open (configurable per theme)
- Modal provides context to child components via `provide/inject`:
  ```javascript
  {
    modal: {
      name: 'modal-name',
      open: function,
      close: function
    }
  }
  ```
- Uses `body-scroll-lock` library for scroll management
- Modal transitions are theme-specific (`modal-transition-{theme}`)
- For fullscreen and aside themes, scroll locking applies to modal body, not page body