hx-swap

Пример

<!-- Replace content in container -->
<div hx-get="..." hx-swap="innerHTML"></div>

<!-- Append to list and scroll down -->
<div hx-get="..." hx-swap="beforeend scroll:bottom"></div>

<!-- Update form with smooth transition -->
<form hx-post="..." hx-swap="outerHTML transition:true"></form>

Методы замены

innerHTML

Заменяет содержимое внутри элемента.

<div hx-get="..." hx-swap="innerHTML">
  <!-- This... -->
  ...
  <!-- ...gets replaced -->
</div>

outerHTML

Заменяет весь элемент.

<!-- This... -->
<div hx-get="..." hx-swap="outerHTML">
  ...
</div>
<!-- ...gets replaced -->

textContent

Заменяет текстовое содержимое элемента, не разбирая ответ как HTML.

<span hx-get="..." hx-swap="textContent">0</span>

Удобно для ответов в виде обычного текста, когда нужно избежать внедрения HTML.

beforebegin / before

Вставляет содержимое перед элементом.

<!-- Response goes here -->
<div hx-get="..." hx-swap="beforebegin">
  ...
</div>

Также можно использовать hx-swap="before"

afterbegin / prepend

Вставляет содержимое первым дочерним элементом.

<div hx-get="..." hx-swap="afterbegin">
  <!-- Response goes here -->
  ...
</div>

Также можно использовать hx-swap="prepend"

beforeend / append

Вставляет содержимое последним дочерним элементом.

<div hx-get="..." hx-swap="beforeend">
  ...
  <!-- Response goes here -->
</div>

Также можно использовать hx-swap="append"

afterend / after

Вставляет содержимое после элемента.

<div hx-get="..." hx-swap="afterend">
  ...
</div>
<!-- Response goes here -->

Также можно использовать hx-swap="after"

innerMorph

Преобразует содержимое элемента, сохраняя его состояние и фокус.

<div hx-get="..." hx-swap="innerMorph">
  ... <!-- This gets morphed -->
</div>

outerMorph

Преобразует весь элемент, сохраняя его состояние и фокус.

<!-- This... -->
<div hx-get="..." hx-swap="outerMorph">
  ...
</div>
<!-- ...gets morphed -->

Отключить преобразование можно с помощью:

• hx-morph-skip: атрибуты и дочерние элементы
• hx-morph-skip-children: только дочерние элементы; атрибуты по-прежнему преобразуются

Глобальные селекторы: htmx.config.morphSkip / htmx.config.morphSkipChildren

outerSync

Преобразует атрибуты целевого элемента, а затем заменяет его дочерние элементы.

<!-- These attributes... -->
<section id="main" hx-get="..." hx-swap="outerSync">
  <!-- ...are morphed -->

  <!-- These children... -->
  ...
  <!-- ...are replaced -->
</section>

Целевой элемент остается в DOM, сохраняя обработчики событий и состояние компонента.

delete

Удаляет элемент (содержимое ответа игнорируется).

<!-- This... -->
<div hx-delete="..." hx-swap="delete">
  ...
</div>
<!-- ...is removed -->

none

Не вставляет содержимое.

<div hx-get="..." hx-swap="none">
  <!-- Response not inserted, but OOB swaps happen -->
</div>

Замены hx-swap-oob и <hx-partial> по-прежнему выполняются.

upsert

Обновляет существующие элементы по ID и вставляет новые.

<div hx-get="..." hx-swap="upsert">
  <!-- Existing elements with matching IDs are updated, new ones are inserted -->
</div>

Требуется расширение hx-upsert.

Модификаторы

Настраивайте поведение замены с помощью модификаторов.

transition

Включает API View Transitions для плавных переходов между страницами.

<div hx-swap="innerHTML transition:true"></div>

Глобальное включение: htmx.config.transitions = true

swap

Добавляет задержку перед заменой.

<div hx-swap="innerHTML swap:1s"></div>

Удобно для отображения состояния загрузки или согласования с CSS-анимациями.

По умолчанию: 0ms

settle

Добавляет задержку между заменой и этапом фиксации.

<div hx-swap="innerHTML settle:200ms"></div>

Удобно для синхронизации htmx с временем CSS-переходов.

По умолчанию: 1ms

ignoreTitle

Предотвращает обновление заголовка страницы <title>.

<div hx-swap="innerHTML ignoreTitle:true"></div>

По умолчанию htmx обновляет заголовок страницы из тегов <title> ответа.

scroll

Автоматически прокручивает страницу к замененному содержимому.

<div hx-swap="beforeend scroll:bottom"></div>

Удобно для бесконечной прокрутки, сообщений чата или привлечения внимания к новому содержимому.

Значения: top, bottom

Укажите другой элемент:

<div hx-swap="innerHTML scroll:top scrollTarget:#other"></div>

Прокрутите окно:

<div hx-swap="innerHTML scroll:window:top"></div>

show

Прокручивает страницу, чтобы целевой элемент оказался в области просмотра.

<div hx-swap="innerHTML show:top"></div>

Значения: top, bottom, none

Укажите другой элемент:

<div hx-swap="innerHTML show:top showTarget:#other"></div>

Для форм с усиленной обработкой по умолчанию используется show:top. Отключение:

<form hx-swap="show:none"></form>

focusScroll

Определяет, будет ли при восстановлении фокуса после замены прокручиваться страница к элементу в фокусе.

<input id="search" hx-get="/search" hx-swap="innerHTML focusScroll:true">

По умолчанию: htmx.config.defaultFocusScroll

target

Задает целевой элемент для замены.

<div hx-swap="innerHTML target:#results"></div>

Альтернатива атрибуту hx-target.

strip

Определяет, удаляется ли внешний элемент ответа.

Ответ:

<section><p>Hello</p></section>

Результат:

<!-- strip:true -->
<div id="target"><p>Hello</p></div>

<!-- strip:false -->
<div id="target"><section><p>Hello</p></section></div>

swapEmpty

Определяет поведение основного целевого элемента, если основного содержимого не осталось.

Сервер может отправить:

<div id="notice" hx-swap-oob="true">Updated</div>

После извлечения htmx обновления hx-swap-oob основного содержимого не остается:

(empty)

Используйте swapEmpty, чтобы сохранить целевой элемент или очистить его:

<!-- Keep the main target -->
<div hx-swap="innerHTML swapEmpty:false">Original</div>

<!-- These are equivalent -->
<div hx-swap="innerHTML swapEmpty:true">Original</div>
<div hx-swap="innerHTML swapEmpty">Original</div>

Поведение по умолчанию: пропустить замену, если были извлечены частичные фрагменты или замены OOB (если только htmx.config.allowEmptySwapAfterOOB не имеет значения true)

Ограничения

• Для <body> значение outerHTML работает как outerSync:

  <!-- This... -->
  <body hx-get="..." hx-swap="outerHTML">...</body>
  
  <!-- ...behaves like this -->
  <body hx-get="..." hx-swap="outerSync">...</body>

  Это связано с тем, что замена <body> удалит его обработчики событий и состояние.

См. также

• HX-Reswap