If you have ever used the #createDocumentFragment API then you probably have an idea of what fragments are, and although a fragments children can become a part of the DOM tree, the fragment itself is a transparent compound element that does not itself exist within the DOM tree.

This puts us into a few tricky patches when trying to implement fragments that behave correctly under the load of difference DOM operations.

The #createDocumentFragment API and DocumentFragment DOM node don’t provide this out of the box. It might not even have been designed for this specific use case in question.

As such unlike `DocumentFragment` we do intend to have persistent fragments that is, if we remove/insert/append a fragment we expect these effects to ripple to its parts, its children — beyond the first attempt we take to mount it to the DOM.

Essentially this is what describes the limitations of DocumentFragment that we want to circumvent.

That said if you do want persistent fragments to behave correctly then it is no secret that it would be a tricky business beyond the first phase.

The easiest piece of the pie is creating and removing fragments. We can either implement this on top of document.createDocumentFragment or branch these operations unto each element that is a child of the fragment.

Beyond that, matters become less straight forward.

## A fragments parent

Considering a fragments parent is itself could be a fragment. How would we handle this give we need to preserve a reference to an actual parent element that exists in the DOM?

Should we consider that its parent should instead become the fragments parent; That is to say a recursive structure such that for any number of levels up the nest, the parent of a particular fragment should always have a reference to the last non-fragment parent.

We could avoid this depending on the goals of the implementation we want to build, for my given case it was imperative that i avoid touching the DOM, for example we could retrieve a reference to a particular nodes parent through the parentNode property;

Given that constraint without the assumption presented before, we would be unable to execute insertBefore operations within the fragment. This assumption and implementation detail will come in handy when discussing the other branches to follow and but mostly exists because of the assumption that we don’t want to touch the DOM to retrieve a reference to a particular nodes parentNode when ever we execute operations within the fragments context.

## Appending to fragments

It might seem strange that appending to a fragment would be a branch case since in isolation we could over look this case entirely. But since fragments can appear between other elements(fragments or otherwise) in any number of ways, this begs us to consider a better approach to preserve a fragments position within the DOM.

Since we might expect fragments to have children we could use the last element of the fragments children and apply append operations as insert operations before this tail element. However this makes the assumption that a fragment always has children.

To this end adding padding elements allow us to insert before the fragments tail element irregardless of the number of children a fragment has over time.

In summary an append operation to a fragment is a proxy of an insert before the tail element of the fragment. We also have to make sure a tail element always exists.

## Inserting before fragments

Like appending to fragments this branch case is solved by having a static head element, not to be confused with the DOM <head> element, this would be an element that is always the first element of the fragment.

As long as fragments always have static edges, in this case a head element. Regardless of its contents we can always insert before a given fragment through this anchor element.

## Conclusion

Given how easy it might be to just get working, the edge cases involved mean that it’s also easy to get it wrong.

All in all this servers as a documentation of what i experienced while implementing this into the next version of DIO.

For my use case i found that moving to a Linked List(circular) data-structure instead of the traditional Arrays for representing a list of children better served the goals i had of supporting Fragments and other similar transparent compound nodes like Portals and Promises, among other implementation choices.

Given the applications that fragments make possible and the shear attraction of it, i do hope other libraries adopt a pattern to support fragments. React 16 and Mithril 1.0 are among the first to get behind this that i know of, maybe others will follow suit. Regardless, if you are working on an implementation i hope this has helped get an idea of what it might entail.

If you want persistent fragments to exist as a native DOM node in the future, consider weighing in on this proposal-fragments or creating one that better articulates the sphere of influence something like this would cover.