# fragment(html)

- [API](#api)
- [How it works](#how-it-works)

---

### API

Generates a trusted HTML [vnode](vnodes.md)

`vnode = m.fragment(attrs, children)`

Argument    | Type                 | Required | Description
----------- | -------------------- | -------- | ---
`attrs`     | `Object`             | Yes      | A map of attributes
`children`  | `Array<Vnode>`       | Yes      | A list of vnodes
**returns** | `Vnode`              |          | A fragment [vnode](vnodes.md)

[How to read signatures](signatures.md)

---

### How it works

`m.fragment()` creates a [fragment vnode](vnodes.md) with attributes. It is meant for advanced use cases involving [keys](keys.md) or [lifecyle methods](lifecycle-methods.md).

A fragment vnode represents a list of DOM elements. If you want a regular element vnode that represents only one DOM element, you should use [`m()`](hyperscript.md) instead.

Normally you can use simple arrays instead to denote a list of nodes:

```javascript
var groupVisible = true

m("ul", [
	m("li", "child 1"),
	m("li", "child 2"),
	groupVisible ? [
		// a fragment containing two elements
		m("li", "child 3"),
		m("li", "child 4"),
	] : null
])
```

However, Javascript arrays cannot be keyed or hold lifecycle methods. One option would be to create a wrapper element to host the key or lifecycle method, but sometimes it is not desirable to have an extra element (for example in complex table structures). In those cases, a fragment vnode can be used instead.

There are a few benefits that come from using `m.fragment` instead of handwriting a vnode object structure: m.fragment creates [monomorphic objects](vnodes.md#monomorphic-class), which have better performance characteristics than creating objects dynamically. In addition, using `m.fragment` makes your intentions clear to other developers, and it makes it less likely that you'll mistakenly set attributes on the vnode object itself rather than on its `attrs` map.