Тег dialog (от английского dialog, «диалог») задаёт окно поверх страницы: подтверждение, форму или сообщение. Пока скрипт или атрибут open окно не открыли, оно закрыто и не занимает места, а метод showModal() делает его модальным: страница позади перестаёт отвечать на клики, а Esc закрывает окно. Закрывающий </dialog> обязателен.
Основы и пример с подтверждением удаления разобраны в уроке «Модальное окно на HTML без JS-библиотек: тег dialog». В статье собраны способы открыть и закрыть окно, returnValue, события, задний фон, стили, прокрутка страницы, анимация, фокус и вложенные окна. Раскрывающиеся блоки описаны на страницах про тег details и тег summary, а другие теги группы в шпаргалке по всем тегам html.
<button type="button" id="open">Удалить файл</button>
<dialog id="confirm">
<p>Удалить файл?</p>
<form method="dialog">
<button value="cancel">Отмена</button>
<button value="ok">Удалить</button>
</form>
</dialog>
const dialog = document.getElementById("confirm");
document.getElementById("open").addEventListener("click", () => {
dialog.showModal();
});
В этой статье
- Тег dialog в HTML: что это и как выглядит по умолчанию
- Атрибуты тега dialog: open, closedby и лишние
- Как открыть dialog: showModal, show, open и command
- Как закрыть dialog: close, форма, requestClose и Esc
- Что вернул dialog: returnValue и форма с полем
- События dialog: cancel, close, beforetoggle и toggle
- Задний фон dialog: ::backdrop и клик вне окна
- Размер и положение dialog: стили и ловушка display: flex
- Длинное окно и прокрутка страницы за dialog
- Анимация открытия и закрытия dialog
- Фокус и доступность dialog: Tab, autofocus и название окна
- Несколько окон: вложенные dialog, Esc и верхний слой
- Почему тег dialog не работает
Тег dialog в HTML: что это и как выглядит по умолчанию
Сначала о том, как выглядит и где находится окно, пока скрипт его не открыл.
Без атрибута open окно закрыто: у него display: none, места на странице оно не занимает, а содержимое пользователю не видно. Когда окно открыто, браузер выводит его с белым фоном, рамкой в 3 пикселя, внутренним отступом 16 пикселей и шириной по содержимому. Цвет текста окно задаёт само, поэтому от body он не наследуется. Внутри допустим любой поточный контент: абзацы, заголовки, форма, изображения.
Положение зависит от способа открытия. Модальное окно браузер выводит по центру экрана и по горизонтали, и по вертикали, а его размер ограничивает экраном за вычетом 38 пикселей. Немодальное окно по горизонтали тоже по центру, а по вертикали остаётся там, где оно записано в разметке.
<dialog>
<p>Окно закрыто и не видно.</p>
</dialog>
<dialog open>
<p>Окно открыто, но немодальное.</p>
</dialog>
Атрибуты тега dialog: open, closedby и лишние
Собственных атрибутов у dialog немного, зато есть атрибуты, которые на нём записывать не нужно.
| Атрибут | Что делает | Пример записи |
|---|---|---|
open | Булев атрибут: окно открыто, но немодально. Убрать его из разметки значит закрыть окно, а запись open="false" окно не закрывает и считается ошибкой | <dialog open> |
closedby | Что закрывает окно: any закрывает по Esc и клику по фону, closerequest только по Esc, none не закрывает ни тем, ни другим. Работает в Firefox с версии 141 и в браузерах на Blink с версии 134, в Safari пока в тестовой версии | closedby="any" |
aria-label, aria-labelledby | Название окна для программ чтения. Без него окно объявляется просто диалогом | aria-labelledby="title" |
role | Роль dialog у тега уже есть, поэтому записывать её не нужно. Для срочного подтверждения записывают role="alertdialog" | role="alertdialog" |
tabindex | Окну фокус не нужен, а с tabindex оно становится лишней остановкой при Tab | tabindex="-1" |
Атрибут aria-modal браузер в разметку сам не записывает, но в структуре доступности модальное окно помечено, а страница позади из неё исключена.
Как открыть dialog: showModal, show, open и command
Способ открытия задаёт, будет окно модальным или нет, и поменять это потом нельзя.
Метод showModal() открывает окно модально. Страница позади перестаёт отвечать на клики и на Tab, окно попадает в верхний слой браузера и выводится выше любых элементов, даже с z-index: 9999. Метод show() и атрибут open открывают немодальное окно: страница остаётся доступной, Esc окно не закрывает, а плашка с большим z-index его перекрывает. Запись dialog.open = true действует как атрибут.
Повторный вызов showModal() у модального окна ошибки не даёт. Если окно уже открыто немодально, showModal() вызывает InvalidStateError. То же будет, если элемента нет в документе. Метод show() у модального окна тоже даёт эту ошибку. Поэтому окно с атрибутом open в разметке модальным уже не сделать.
Без скрипта окно открывает кнопка с атрибутами command="show-modal" и commandfor с id окна. Атрибут command работает в Firefox с версии 144, в Safari 26.2 и в браузерах на Blink с версии 135.
<button command="show-modal" commandfor="confirm">
Удалить файл
</button>
Пример: способы открыть окно
Выберите способ: в статусе видно, модальное ли окно и где оно находится. После showModal() кнопка страницы не отвечает на клики, а после show() и атрибута open отвечает и счётчик растёт. Вариант command работает без скрипта в новых версиях браузеров.
Как закрыть dialog: close, форма, requestClose и Esc
Окно закрывают несколькими способами, и они различаются событием cancel и значением returnValue.
Метод close() закрывает окно сразу, а его необязательный аргумент записывается в returnValue. Форма с method="dialog" закрывает окно при отправке без обращения к серверу. Метод requestClose() запрашивает закрытие, как Esc: сначала приходит событие cancel, которое можно отменить, и только потом окно закрывается. Клавиша Esc закрывает только модальное окно, у окна из show() она ничего не делает.
| Способ закрытия | Событие cancel | Значение returnValue |
|---|---|---|
| Esc | Приходит, его можно отменить | Сбрасывается в пустую строку |
close() | Нет | Не меняется |
close("x") | Нет | Строка x |
requestClose() | Приходит, его можно отменить | Не меняется |
requestClose("x") | Приходит, его можно отменить | Строка x |
Кнопка в форме method="dialog" | Нет | Значение value кнопки |
dialog.close();
dialog.close("saved");
dialog.requestClose();
Что вернул dialog: returnValue и форма с полем
Свойство returnValue хранит строку, которую окно вернуло при закрытии.
Если окно закрыла кнопка формы с method="dialog", в returnValue попадает её value. Читать значение удобно в обработчике события close. Поле формы с атрибутом required работает как обычно: пока оно пустое, отправка не проходит, а окно остаётся открытым, и браузер показывает подсказку у поля. Кнопке «Отмена» добавляют formnovalidate, чтобы она закрывала окно при пустом поле. Клавиша Enter в поле отправляет форму первой кнопкой submit. Метод showModal() значение returnValue не сбрасывает, поэтому прошлый результат остаётся до следующего закрытия.
dialog.addEventListener("close", () => {
if (dialog.returnValue === "ok") {
deleteFile();
}
});
Пример: returnValue после закрытия
Откройте окно и закройте его разными способами. Кнопка формы записывает в returnValue своё value, close() с аргументом записывает строку, а Esc сбрасывает значение в пустую строку. Пустое обязательное поле не даёт форме закрыть окно.
События dialog: cancel, close, beforetoggle и toggle
У окна четыре события, и порядок у них зависит от способа закрытия.
Событие cancel приходит перед закрытием по Esc, requestClose() или клику по фону при closedby="any". Оно отменяемое: вызов preventDefault() оставляет окно открытым, но не навсегда: после нескольких нажатий Esc подряд браузер перестаёт считать cancel отменяемым, и окно закрывается. Событие close приходит после закрытия. У окна есть и события beforetoggle и toggle, в отличие от details, где beforetoggle не бывает. При открытии приходит beforetoggle, затем toggle. При закрытии по Esc порядок такой: cancel, beforetoggle, close, toggle, а при close() события идут так: beforetoggle, toggle, close. Ни одно из событий не всплывает, поэтому слушатель вешают на сам dialog.
dialog.addEventListener("cancel", (e) => {
e.preventDefault();
});
Пример: события при открытии и закрытии
Откройте окно, затем закройте его кнопкой и через Esc, сравните порядок событий. Если отметить отмену, Esc вызовет cancel, но окно останется открытым. После нескольких нажатий подряд браузер всё же закроет окно. События не всплывают к родителям.
Задний фон dialog: ::backdrop и клик вне окна
Затемнённая область за модальным окном называется задним фоном, и клик по ней окно по умолчанию не закрывает.
Задний фон оформляется псевдоэлементом ::backdrop: по умолчанию это чёрный цвет с прозрачностью 10 процентов. Он выводится только у модального окна и накрывает весь экран. Клик по фону приходит самому dialog, и клик по рамке или внутреннему отступу окна даёт точно такое же событие с тем же target. Поэтому закрытие по условию e.target === dialog срабатывает и от клика по краю окна. Надёжнее сравнить координаты клика с границами окна из getBoundingClientRect().
Без скрипта то же делает атрибут closedby="any": окно закрывается кликом по фону, но не кликом по рамке или отступам, и не закрывается, когда выделение текста началось внутри окна, а мышь отпустили на фоне. Событие cancel при этом приходит как при Esc. Режим none отключает даже Esc, поэтому в таком окне нужна видимая кнопка закрытия. В ::backdrop работают переменные, заданные на :root и на самом окне.
dialog::backdrop {
background: rgba(31, 36, 48, 0.55);
backdrop-filter: blur(2px);
}
Пример: закрытие по клику на задний фон
Выберите режим, откройте окно и кликните по затемнению, по краю окна и по его отступу. Атрибут closedby закрывает окно только от клика по фону. Простое условие e.target === dialog закрывает окно и от клика по отступу, а сравнение с координатами не закрывает.
Размер и положение dialog: стили и ловушка display: flex
Размер и вид окна задают обычными свойствами, но одно правило легко сломать закрытие.
Ширину, отступы, рамку и скругление окна меняют как у любого блока. Стандартный отступ равен 16 пикселям, рамка 3 пикселям. Чтобы убрать их, значения задают явно. Правило display: flex или display: grid у dialog без уточнения перебивает display: none закрытого окна, и оно остаётся на странице. Поэтому такие правила записывают для dialog[open].
dialog[open] {
display: flex;
flex-direction: column;
gap: 8px;
}
Пример: display у закрытого окна
Правило display: flex у dialog без [open] перебивает display: none, и закрытое окно остаётся на странице. Запись dialog[open] действует только у открытого окна и закрытое не показывает.
Длинное окно и прокрутка страницы за dialog
Длинное окно прокручивается внутри себя, но страница позади по умолчанию продолжает прокручиваться.
У модального окна максимальная высота ограничена экраном, а overflow по умолчанию равен auto, поэтому длинное содержимое получает свою полосу прокрутки без дополнительных правил. Колесо мыши над затемнённым фоном при этом прокручивает страницу позади. Запретить это можно правилом body:has(dialog:modal) { overflow: hidden; }: оно действует, пока в документе есть открытое модальное окно, и отключается само после закрытия. При этом ширина страницы может измениться на размер полосы прокрутки, и содержимое сдвинется.
body:has(dialog:modal) {
overflow: hidden;
}
Пример: длинное окно и прокрутка страницы
Откройте окно и покрутите колесо мыши над затемнённым фоном, затем над самим окном. Без блокировки страница позади прокручивается, с правилом body:has(dialog:modal) нет, а длинное окно прокручивается внутри себя.
Анимация открытия и закрытия dialog
Окно можно показывать и прятать плавно, но для этого нужны два специальных приёма.
Закрытое окно имеет display: none, а такое значение обычный transition не анимирует. Поэтому в переход добавляют display и overlay со значением allow-discrete: тогда окно остаётся на экране, пока идёт затухание, и убирается в конце. Для плавного появления нужно ещё правило @starting-style с начальным значением, иначе окно сразу получает конечное. Без него закрытие плавное, а открытие мгновенное. Задний фон анимируют так же, записав правила для dialog::backdrop.
dialog {
opacity: 0;
transition: opacity .4s, display .4s allow-discrete,
overlay .4s allow-discrete;
}
dialog[open] {
opacity: 1;
}
@starting-style {
dialog[open] {
opacity: 0;
}
}
Пример: плавное открытие и закрытие окна
Выберите вариант, откройте и закройте окно: в статусе меняется прозрачность. Закрытие становится плавным уже после transition с allow-discrete, а для открытия нужно ещё правило @starting-style.
Фокус и доступность dialog: Tab, autofocus и название окна
Фокус и его возврат браузер настраивает сам, но поведение можно уточнить.
При открытии модального окна фокус получает первый элемент, который можно сфокусировать. Если такого элемента нет, фокус получает само окно. Атрибут autofocus у нужной кнопки выбирает другой элемент, например безопасную кнопку «Отмена». Клавиша Tab ходит по элементам окна и не попадает на страницу позади: после последнего элемента фокус уходит в интерфейс браузера и возвращается к первому. После закрытия фокус возвращается на элемент, который окно открыл.
В структуре доступности у окна роль диалога, а у модального окна ещё и признак модальности. Страница позади из структуры исключена. Название окну задают через aria-labelledby со ссылкой на заголовок или через aria-label. Для срочных подтверждений, например перед удалением, записывают role="alertdialog".
<dialog aria-labelledby="title">
<h2 id="title">Удалить файл?</h2>
<button autofocus>Отмена</button>
<button>Удалить</button>
</dialog>
Пример: фокус в модальном окне
Откройте окно и нажимайте Tab: фокус ходит по кнопкам окна, а затем уходит в интерфейс браузера и возвращается. С autofocus окно сразу переводит фокус на вторую кнопку. После закрытия фокус возвращается на кнопку, которая открывала окно.
Несколько окон: вложенные dialog, Esc и верхний слой
Модальных окон можно открыть несколько подряд, и каждое следующее оказывается выше предыдущего.
Новое модальное окно попадает в верхний слой над прежним, и страница вместе с первым окном перестаёт отвечать на клики. Клавиша Esc закрывает сначала верхнее окно, потом первое. Вложенный в окно dialog допустим и открывается тем же showModal(). Фон каждого открытого окна затемняет страницу, поэтому при нескольких окнах затемнение складывается и страница становится темнее.
Для подсказок и меню, которые не должны блокировать страницу, подходит атрибут popover: в режиме по умолчанию он закрывается по клику вне элемента, а блокировать страницу не умеет. Если страница позади должна быть недоступна, нужен dialog с showModal().
Пример: два окна друг над другом
Откройте первое окно, из него второе и нажмите Esc дважды: сначала закрывается верхнее окно, потом первое. Страница и первое окно позади второго не отвечают на клики.
Почему тег dialog не работает
Причины чаще всего в способе открытия, в соседних правилах или в записи атрибутов.
| Что видно | Причина | Что сделать |
|---|---|---|
Окно с атрибутом open не затемняет страницу и не закрывается по Esc | Атрибут open открывает окно немодально | Открыть окно методом showModal() или кнопкой с command |
showModal() даёт InvalidStateError | Окно уже открыто немодально или его нет в документе | Убрать open из разметки, добавить окно в документ |
| Закрытое окно остаётся на странице | У dialog записан display: flex или grid | Записать правило для dialog[open] |
| Клик по фону окно не закрывает | Закрытие по фону по умолчанию не включено | Добавить closedby="any" или свой обработчик |
| Окно закрывается от клика по краю | Условие e.target === dialog срабатывает и по рамке | Сравнить координаты клика с getBoundingClientRect() |
| Esc не закрывает окно | Окно открыто через show() или записан closedby="none" | Открыть через showModal(), убрать none |
| Окно с полем не закрывается кнопкой | Обязательное поле пустое, отправка формы не проходит | Заполнить поле или добавить кнопке formnovalidate |
| Страница позади прокручивается | Прокрутку страницы окно не блокирует | Запретить прокрутку body, пока открыто модальное окно, через :has() |
| Окно появляется без анимации | Нет правила @starting-style | Добавить правило с начальным значением |
Частые ошибки с тегом dialog
Эти записи выглядят рабочими, но ведут себя иначе, чем ожидается.
| Ошибка | Что происходит | Как исправить |
|---|---|---|
<dialog open> | Окно немодальное: страница доступна, Esc ничего не делает | Открыть методом showModal() |
open="false" | Атрибут считается заданным, окно остаётся открытым | Убрать атрибут целиком |
dialog { display: flex; } | Закрытое окно остаётся на странице | Записать dialog[open] |
closedby="none" | Окно не закрывается и по Esc | Оставить видимую кнопку закрытия или убрать значение |
<dialog tabindex="0"> | Лишний пункт в порядке фокуса | Убрать атрибут |
<dialog role="dialog"> | Роль у тега уже есть, валидатор отмечает её как лишнюю | Убрать role |
<p><dialog> | Окно внутри абзаца ломает разметку: абзац закрывается раньше | Записать окно вне абзаца |
<button><dialog> | Окно внутри кнопки недопустимо | Записать окно рядом с кнопкой |