Skip to content

Add hx-swap-oob modifier support #3352

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: dev
Choose a base branch
from

Conversation

MichaelWest22
Copy link
Collaborator

@MichaelWest22 MichaelWest22 commented Jun 26, 2025

Description

This Change re-implements hx-swap-oob swapping to use the full htmx swap function and all of its various modifiers and adds two additional modifiers for additional oob functionality. The recent refactors of the swap function to support history, delay and transitions have now enabled us to reuse swap() much easier than before!

Core to this change is the full backwards compatibility with existing hx-swap-oob use cases where the attribute value can be a <swapStyle>:<selector> format. With the old format the swapStyle portion could never contain white space as only a single word swap style was usable so we can use this fact to search for whitespace and when it exists treat the whole attribute value as a normal hx-swap style value instead and reuse all existing code paths we can.

target: modifier

To support a custom target selector I've added a target: modifier that only works with oob swaps and allows parsing of multiple words after target: to be used as a complex extended selector.

strip: modifier

The oob tags are set to be stripped off by default in all but outerHTML swap styles to make oob behaviour simple for inner style swaps but it is helpful sometimes to override this default to allow various other kinds of swap behaviors like doing an outerHTML style swap of an oob tags inner contents to place multiple items easily over top of a single target element. So I've added a strip:true and strip:false options that allows you to easily override it with this modifier.

template handling

This change also includes support for oob tags to be template tags themselves instead of just wrapping template tags around them which simplifies tag choice when dealing with tables and other element types. This just required using fragment.content if the oob element happened to be a template element

hx-select/hx-select-oob

hx-select tested working with strip:true and hx-select-oob updated to be fully backwards compatible with its old undocumented id only format and now supports css selectors properly as this was documented but not working properly and it now supports full hx-swap-oob syntax as well.

idiomroph advanced oob swap support

This change now allows hx-oob-swap to support : in the swap style which allows morph:innerHTML swap styles that were not usable before.

Corresponding issue:
#2308
#3316

Testing

Performed some manual testing of various hx-swap-oob actions and added many tests for the various core functions.

Checklist

  • I have read the contribution guidelines
  • I have targeted this PR against the correct branch (master for website changes, dev for
    source changes)
  • This is either a bugfix, a documentation update, or a new feature that has been explicitly
    approved via an issue
  • I ran the test suite locally (npm run test) and verified that it succeeded

@MichaelWest22 MichaelWest22 added the enhancement New feature or request label Jun 26, 2025
// Avoid polluting the DOM with empty templates that were only used to encapsulate oob swap
template.remove()
}
})

// normal swap
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This comment no longer seems to be true.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yeah its a bit confusing as I named a variable the same name for a different purpose. I've renamed that variable to avoid this confusion now. This is still the normal part of the swap function compared to the part where it can do oob swaps. Now if isOOBSwap is true then the oob swap case will skip the oob swap sections to avoid recursion and just do a normal swap of its oob content.

@MichaelWest22 MichaelWest22 force-pushed the hx-swap-oob-modifiers branch from 7d955e5 to 152ebf4 Compare July 3, 2025 04:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants