insert

Places children into a parent without creating a root, so they are owned by the surrounding scope. It is the lower-level cousin of render: same mounting, but it does not wrap the content in a fresh root and does not return a disposer.

Because it relies on the current reactive owner, call insert from inside one — typically a component body or an existing root. Its content disposes when that surrounding scope disposes. Use it to project content into a different DOM location while keeping it tied to the lifecycle of the place that created it.

Like render, inserting into a container does not clear the container by default, and the inserted content removes only its own nodes on disposal.

Arguments

name	type	description
children	JSX.Element	thing to insert
parent?	Element | DocumentFragment | null	mount point (default: document.body); a ShadowRoot is a DocumentFragment
options?	{ clear?: boolean; relative?: boolean }	clear empties the target before inserting; relative inserts before parent instead of appending

Returns: the created node(s) — a Node, an array of Nodes, or undefined, depending on what children resolves to. Not a disposer.

insert vs render

• render creates a fresh root, mounts the content, and returns a dispose function. Call it to bootstrap an app or mount an independently-managed subtree.
• insert skips the root and returns the inserted node(s). Call it from inside an existing owner when the content should live and die with that owner.

Examples

Project content into another element

Insert from inside a component so the inserted content is owned by that component — it disposes automatically when the component does.

import { insert, render, signal } from 'pota'

const host = document.createElement('aside')
host.style.cssText = 'border:1px dashed #888; padding:.5rem'
document.body.append(host)

function App() {
	const message = signal('hello from outside')

	// owned by App's scope — its content disposes with App
	insert(<p>{message.read}</p>, host)

	return (
		<p>
			<button on:click={() => message.write('updated!')}>
				update sidebar
			</button>
		</p>
	)
}

render(App)

Clear the target first

Pass { clear: true } to empty the target element before inserting.

import { insert, render } from 'pota'

function App() {
	return <main>original content</main>
}

render(App)

render(() => {
	insert(
		<span>replaced content</span>,
		document.querySelector('main'),
		{
			clear: true,
		},
	)
	return null
})