# Preact Documentation

This file contains comprehensive documentation for Preact v10, a fast 3kB alternative to React with the same modern API.
Preact is a fast, lightweight alternative to React that provides the same modern API in a much smaller package. This documentation covers all aspects of Preact v10, including components, hooks, server-side rendering, TypeScript support, and more.

---

## Introduction

**Description:** How to get started with Preact. We'll learn how to setup the tooling (if any) and get going with writing an application

### Getting Started

New to Preact? New to Virtual DOM? Check out the [tutorial](/tutorial).

This guide helps you get up and running to start developing Preact apps, using 3 popular options.
If you're new to Preact, we recommend starting with [Vite](#create-a-vite-powered-preact-app).



#### No build tools route

Preact is packaged to be used directly in the browser, and doesn't require any build or tools:

```html
<script type="module">
	import { h, render } from 'https://esm.sh/preact';

	// Create your app
	const app = h('h1', null, 'Hello World!');

	render(app, document.body);
</script>
```

The primary drawback of developing this way is the lack of JSX, which requires a build step. An ergonomic and performant alternative to JSX is documented in the next section.

##### Alternatives to JSX

Writing raw `h` or `createElement` calls can be tedious. JSX has the advantage of looking similar to HTML, which makes it easier to understand for many developers in our experience. JSX requires a build step though, so we highly recommend an alternative called [HTM][htm].

[HTM][htm] is a JSX-like syntax that works in standard JavaScript. Instead of requiring a build step, it uses JavaScript's own [Tagged Templates](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#Tagged_templates) syntax, which was added in 2015 and is supported in [all modern browsers](https://caniuse.com/#feat=template-literals). This is an increasingly popular way to write Preact apps, since there are fewer moving parts to understand than a traditional front-end build tooling setup.

```html
<script type="module">
	import { h, render } from 'https://esm.sh/preact';
	import htm from 'https://esm.sh/htm';

	// Initialize htm with Preact
	const html = htm.bind(h);

	function App(props) {
		return html`
			<h1>Hello ${props.name}!</h1>
		`;
	}

	render(
		html`<${App} name="World" />`,
		document.body
	);
</script>
```

> **Tip:** HTM also provides a convenient single-import Preact version:
>
> `import { html, render } from 'https://esm.sh/htm/preact/standalone'`

For a more scalable solution, see [Import Maps -- Basic Usage](/guide/v10/no-build-workflows#basic-usage), and for more information on HTM, check out its [documentation][htm].

[htm]: https://github.com/developit/htm

#### Create a Vite-Powered Preact App

[Vite](https://vitejs.dev) has become an incredibly popular tool for building applications across many frameworks in the past couple of years, and Preact is no exception. It's built upon popular tooling like ES modules, Rollup, and ESBuild. Vite, through our initializer or their Preact template, requires no configuration or prior knowledge to get started and this simplicity makes it a very popular way to use Preact.

To get up and running with Vite quickly, you can use our initializer `create-preact`. This is an interactive command-line interface (CLI) app that can be run in the terminal on your machine. Using it, you can create a new application by running the following:

```bash
npm init preact
```

This will walk you through creating a new Preact app and gives you some options such as TypeScript, routing (via `preact-iso`), and ESLint support.

> **Tip:** None of these decisions need to be final, you can always add or remove them from your project later if you change your mind.

##### Getting ready for development

Now we're ready to start our application. To start a development server, run the following command inside your newly generated project folder:

```bash
# Go into the generated project folder
cd my-preact-app

# Start a development server
npm run dev
```

Once the server has started, it will print a local development URL to open in your browser.
Now you're ready to start coding your app!

##### Making a production build

There comes a time when you need to deploy your app somewhere. Vite ships with a handy `build` command which will generate a highly-optimized production build.

```bash
npm run build
```

Upon completion, you'll have a new `dist/` folder which can be deployed directly to a server.

> For a full list of all available commands and their options, check out the [Vite CLI Documentation](https://vitejs.dev/guide/cli.html).

#### Integrating Into An Existing Pipeline

If you already have an existing tooling pipeline set up, it's very likely that this includes a bundler. The most popular choices are [webpack](https://webpack.js.org/), [rollup](https://rollupjs.org) or [parcel](https://parceljs.org/). Preact works out of the box with all of them, no major changes needed!

##### Setting up JSX

To transpile JSX, you need a Babel plugin that converts it to valid JavaScript code. The one we all use is [@babel/plugin-transform-react-jsx](https://babeljs.io/docs/en/babel-plugin-transform-react-jsx). Once installed, you need to specify the function for JSX that should be used:

```json
{
	"plugins": [
		[
			"@babel/plugin-transform-react-jsx",
			{
				"pragma": "h",
				"pragmaFrag": "Fragment"
			}
		]
	]
}
```

> [Babel](https://babeljs.io/) has some of the best documentation out there. We highly recommend checking it out for questions surrounding Babel and how to set it up.

##### Aliasing React to Preact

At some point, you'll probably want to make use of the vast React ecosystem. Libraries and Components originally written for React work seamlessly with our compatibility layer. To make use of it, we need to point all `react` and `react-dom` imports to Preact. This step is called _aliasing._

> **Note:** If you're using Vite (via `@preact/preset-vite`), Preact CLI, or WMR, these aliases are automatically handled for you by default.

###### Aliasing in Webpack

To alias any package in Webpack, you need to add the `resolve.alias` section
to your config. Depending on the configuration you're using, this section may
already be present, but missing the aliases for Preact.

```js
const config = {
	//...snip
	resolve: {
		alias: {
			react: 'preact/compat',
			'react-dom/test-utils': 'preact/test-utils',
			'react-dom': 'preact/compat', // Must be below test-utils
			'react/jsx-runtime': 'preact/jsx-runtime'
		}
	}
};
```

###### Aliasing in Node

When running in Node, bundler aliases (Webpack, Rollup, etc.) will not work, as can
be seen in NextJS. To fix this, we can use aliases directly in our `package.json`:

```json
{
	"dependencies": {
		"react": "npm:@preact/compat",
		"react-dom": "npm:@preact/compat"
	}
}
```

###### Aliasing in Parcel

Parcel uses the standard `package.json` file to read configuration options under
an `alias` key.

```json
{
	"alias": {
		"react": "preact/compat",
		"react-dom/test-utils": "preact/test-utils",
		"react-dom": "preact/compat",
		"react/jsx-runtime": "preact/jsx-runtime"
	}
}
```

###### Aliasing in Rollup

To alias within Rollup, you'll need to install [@rollup/plugin-alias](https://github.com/rollup/plugins/tree/master/packages/alias).
The plugin will need to be placed before your [@rollup/plugin-node-resolve](https://github.com/rollup/plugins/tree/master/packages/node-resolve)

```js
import alias from '@rollup/plugin-alias';

module.exports = {
	plugins: [
		alias({
			entries: [
				{ find: 'react', replacement: 'preact/compat' },
				{ find: 'react-dom/test-utils', replacement: 'preact/test-utils' },
				{ find: 'react-dom', replacement: 'preact/compat' },
				{ find: 'react/jsx-runtime', replacement: 'preact/jsx-runtime' }
			]
		})
	]
};
```

###### Aliasing in Jest

[Jest](https://jestjs.io/) allows the rewriting of module paths similar to bundlers.
These rewrites are configured using regular expressions in your Jest configuration:

```json
{
	"moduleNameMapper": {
		"^react$": "preact/compat",
		"^react-dom/test-utils$": "preact/test-utils",
		"^react-dom$": "preact/compat",
		"^react/jsx-runtime$": "preact/jsx-runtime"
	}
}
```

###### Aliasing in TypeScript

TypeScript, even when used alongside a bundler, has its own process of resolving types.
In order to ensure Preact's types are used in place of React's, you will want to add the
following configuration to your `tsconfig.json` (or `jsconfig.json`):

```json
{
  "compilerOptions": {
    ...
    "skipLibCheck": true,
    "baseUrl": "./",
    "paths": {
      "react": ["./node_modules/preact/compat/"],
      "react/jsx-runtime": ["./node_modules/preact/jsx-runtime"],
      "react-dom": ["./node_modules/preact/compat/"],
      "react-dom/*": ["./node_modules/preact/compat/*"]
    }
  }
}
```

Additionally, you may want to enable `skipLibCheck` as we do in the example above. Some
React libraries make use of types that may not be provided by `preact/compat` (though we do
our best to fix these), and as such, these libraries could be the source of TypeScript compilation
errors. By setting `skipLibCheck`, you can tell TS that it doesn't need to do a full check of all
`.d.ts` files (usually these are limited to your libraries in `node_modules`) which will fix these errors.

###### Aliasing with Import Maps

```html
<script type="importmap">
	{
		"imports": {
			"preact": "https://esm.sh/preact@10.23.1",
			"preact/": "https://esm.sh/preact@10.23.1/",
			"react": "https://esm.sh/preact@10.23.1/compat",
			"react/": "https://esm.sh/preact@10.23.1/compat/",
			"react-dom": "https://esm.sh/preact@10.23.1/compat"
		}
	}
</script>
```

See also [Import Maps -- Recipes and Common Patterns](/guide/v10/no-build-workflows#recipes-and-common-patterns) for more examples.

------

**Description:** New features and changes in Preact X

### What's new in Preact X

Preact X is a huge step forward from Preact 8.x. We've rethought every bit and byte of our code and added a plethora of major features in the process. Same goes for compatibility enhancements to support more third-party libraries.

In a nutshell Preact X is what we always wanted Preact to be: A tiny, fast and feature-packed library. And speaking of size, you'll be happy to hear that all the new features and improved rendering fit into the same size footprint as `8.x`!



#### Fragments

`Fragments` are a major new feature of Preact X, and one of the main motivations for rethinking Preact's architecture. They are a special kind of component that renders children elements inline with their parent, without an extra wrapping DOM element. On top of that they allow you to return multiple nodes from `render`.

[Fragment docs →](/guide/v10/components#fragments)

```jsx

function Foo() {
	return (
		<>
			<div>A</div>
			<div>B</div>
		</>
	);
}
```

#### componentDidCatch

We all wish errors wouldn't happen in our applications, but sometimes they do. With `componentDidCatch`, it's now possible to catch and handle any errors that occur within lifecycle methods like `render`, including exceptions deep in the component tree. This can be used to display user-friendly error messages, or write a log entry to an external service in case something goes wrong.

[Lifecycle docs →](/guide/v10/components#error-boundaries)

```jsx

class Catcher extends Component {
	state = { errored: false };

	componentDidCatch(error) {
		this.setState({ errored: true });
	}

	render(props, state) {
		if (state.errored) {
			return <p>Something went badly wrong</p>;
		}
		return props.children;
	}
}
```

#### Hooks

`Hooks` are a new way to make sharing logic easier between components. They represent an alternative to the existing class-based component API. In Preact they live inside an addon which can be imported via `preact/hooks`

[Hooks Docs →](/guide/v10/hooks)

```jsx

function Counter() {
	const [value, setValue] = useState(0);
	const increment = useCallback(() => setValue(value + 1), [value]);

	return (
		<div>
			Counter: {value}
			<button onClick={increment}>Increment</button>
		</div>
	);
}
```

#### createContext

The `createContext`-API is a true successor for `getChildContext()`. Whereas `getChildContext` is fine when you're absolutely sure to never change a value, it falls apart as soon as a component in-between the provider and consumer blocks an update via `shouldComponentUpdate` when it returns `false`. With the new context API this problem is now a thing of the past. It is a true pub/sub solution to deliver updates deep down the tree.

[createContext Docs →](/guide/v10/context#createcontext)

```jsx
const Theme = createContext('light');

function ThemedButton(props) {
	return (
		<Theme.Consumer>{theme => <div>Active theme: {theme}</div>}</Theme.Consumer>
	);
}

function App() {
	return (
		<Theme.Provider value="dark">
			<SomeComponent>
				<ThemedButton />
			</SomeComponent>
		</Theme.Provider>
	);
}
```

#### CSS Custom Properties

Sometimes it's the little things that make a huge difference. With the recent advancements in CSS you can leverage [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/--*) for styling:

```jsx
function Foo(props) {
	return <div style={{ '--theme-color': 'blue' }}>{props.children}</div>;
}
```

#### Compat lives in core

Although we were always keen on adding new features and pushing Preact forward, the `preact-compat` package didn't receive as much love. Up until now it has lived in a separate repository making it harder to coordinate large changes spanning Preact and the compatibility layer. By moving compat into the same package as Preact itself, there's nothing extra to install in order to use libraries from the React ecosystem.

The compatibility layer is now called [preact/compat](/guide/v10/differences-to-react#features-exclusive-to-preactcompat), and has learned several new tricks such as `forwardRef`, `memo` and countless compatibility improvements.

```js
// Preact 8.x
import React from 'preact-compat';

// Preact X
import React from 'preact/compat';
```

#### Many compatibility fixes

These are too many to list, but we've grown bounds and leaps on the compatibility front with libraries from the React ecosystem. We specifically made sure to include several popular packages in our testing process to make sure that we can guarantee full support for them.

If you came across a library that didn't work well with Preact 8, you should give it another go with X. The chances are high that everything works as expected ;)

------

**Description:** Upgrade your Preact 8.x application to Preact X

### Upgrading from Preact 8.x

This document is intended to guide you through upgrading an existing Preact 8.x application to Preact X and is divided in 3 main sections

Preact X brings many new exciting features such as `Fragments`, `hooks` and much improved compatibility with the React ecosystem. We tried to keep any breaking changes to the minimum possible, but couldn't eliminate all of them completely without compromising on our feature set.



#### Upgrading dependencies

_Note: Throughout this guide we'll be using the `npm` client and the commands should be easily applicable to other package managers such as `yarn`._

Let's begin! First install Preact X:

```bash
npm install preact
```

Because compat has moved to core, there is no need for `preact-compat` anymore. Remove it with:

```bash
npm remove preact-compat
```

##### Updating preact-related libraries

To guarantee a stable ecosystem for our users (especially for our enterprise users) we've released major version updates to Preact X related libraries. If you're using `preact-render-to-string` you need to update it to the version that works with X.

| Library                   | Preact 8.x | Preact X |
| ------------------------- | ---------- | -------- |
| `preact-render-to-string` | 4.x        | 5.x      |
| `preact-router`           | 2.x        | 3.x      |
| `preact-jsx-chai`         | 2.x        | 3.x      |
| `preact-markup`           | 1.x        | 2.x      |

##### Compat has moved to core

To make third-party React libraries work with Preact we ship a **compat**ibility layer that can be imported via `preact/compat`. It was previously available as a separate package, but to make coordination easier we've moved it into the core repository. So you'll need to change existing import or alias declarations from `preact-compat` to `preact/compat` (note the slash).

Be careful not to introduce any spelling errors here. A common one seems to be to write `compact` instead of `compat`. If you're having trouble with that, think of `compat` as the `compatibility` layer for react. That's where the name is coming from.

##### Third party libraries

Due to the nature of the breaking changes, some existing libraries may cease to work with X. Most of them have been updated already following our beta schedule but you may encounter one where this is not the case.

###### preact-redux

`preact-redux` is one of such libraries that hasn't been updated yet. The good news is that `preact/compat` is much more React-compliant and works out of the box with the React bindings called `react-redux`. Switching to it will resolve the situation. Make sure that you've aliased `react` and `react-dom` to `preact/compat` in your bundler.

1. Remove `preact-redux`
2. Install `react-redux`

###### mobx-preact

Due to our increased compatibility with the react-ecosystem this package isn't needed anymore. Use `mobx-react` instead.

1. Remove `mobx-preact`
2. Install `mobx-react`

###### styled-components

Preact 8.x only worked up to `styled-components@3.x`. With Preact X this barrier is no more and we work with the latest version of `styled-components`. Make sure that you've [aliased react to preact](/guide/v10/getting-started#aliasing-react-to-preact) correctly.

###### preact-portal

The `Portal` component is now part of `preact/compat`.

1. Remove `preact-portal`
2. Import `createPortal` from `preact/compat`

#### Getting your code ready

##### Using named exports

To better support tree-shaking we don't ship with a `default` export in preact core anymore. The advantage of this approach is that only the code you need will be included in your bundle.

```js
// Preact 8.x
import Preact from 'preact';

// Preact X
import * as preact from 'preact';

// Preferred: Named exports (works in 8.x and Preact X)
import { h, Component } from 'preact';
```

_Note: This change doesn't affect `preact/compat`. It still has both named and a default export to remain compatible with react._

##### `render()` always diffs existing children

In Preact 8.x, the calls to `render()` would always append the elements to the container.

```jsx
// Existing markup:
<body>
	<div>hello</div>
</body>;

render(<p>foo</p>, document.body);
render(<p>bar</p>, document.body);

// Preact 8.x output:
<body>
	<div>hello</div>
	<p>foo</p>
	<p>bar</p>
</body>;
```

In order to diff existing children in Preact 8, an existing DOM node had to be provided.

```jsx
// Existing markup:
<body>
	<div>hello</div>
</body>;

let element;
element = render(<p>foo</p>, document.body);
element = render(<p>bar</p>, document.body, element);

// Preact 8.x output:
<body>
	<div>hello</div>
	<p>bar</p>
</body>;
```

In Preact X, `render()` always diffs DOM children inside of the container. So if your container contains DOM that was not rendered by Preact, Preact will try to diff it with the elements you pass it. This new behavior more closely matches the behavior of other VDOM libraries.

```jsx
// Existing markup:
<body>
	<div>hello</div>
</body>;

render(<p>foo</p>, document.body);
render(<p>bar</p>, document.body);

// Preact X output:
<body>
	<p>bar</p>
	<div>hello</div>
</body>;
```

If you are looking for behavior that exactly matches how React's `render` method works, use the `render` method exported by `preact/compat`.

##### `props.children` is not always an `array`

In Preact X we can't guarantee `props.children` to always be of type `array` anymore. This change was necessary to resolve parsing ambiguities in regards to `Fragments` and components that return an `array` of children. In most cases you may not even notice it. Only in places where you'll use array methods on `props.children` directly need to be wrapped with `toChildArray`. This function will always return an array.

```jsx
// Preact 8.x
function Foo(props) {
	// `.length` is an array method. In Preact X when `props.children` is not an
	// array, this line will throw an exception
	const count = props.children.length;
	return <div>I have {count} children </div>;
}

// Preact X
import { toChildArray } from 'preact';

function Foo(props) {
	const count = toChildArray(props.children).length;
	return <div>I have {count} children </div>;
}
```

##### Don't access `this.state` synchronously

In Preact X the state of a component will no longer be mutated synchronously. This means that reading from `this.state` right after a `setState` call will return the previous values. Instead you should use a callback function to modify state that depends on the previous values.

```jsx
this.state = { counter: 0 };

// Preact 8.x
this.setState({ counter: this.state.counter + 1 });

// Preact X
this.setState(prevState => {
	// Alternatively return `null` here to abort the state update
	return { counter: prevState.counter + 1 };
});
```

##### `dangerouslySetInnerHTML` will skip diffing of children

When a `vnode` has the property `dangerouslySetInnerHTML` set Preact will skip diffing the `vnode's` children.

```jsx
<div dangerouslySetInnerHTML="foo">
	<span>I will be skipped</span>
	<p>So will I</p>
</div>
```

#### Notes for library authors

This section is intended for library authors who are maintaining packages to be used with Preact X. You can safely skip this section if you're not writing one.

##### The `VNode` shape has changed

We renamed/moved the following properties:

- `attributes` -> `props`
- `nodeName` -> `type`
- `children` -> `props.children`

As much as we tried, we always ran into edge-cases with third-party libraries written for react. This change to our `vnode` shape removed many difficult to spot bugs and makes our `compat` code a lot cleaner.

##### Adjacent text nodes are not joined anymore

In Preact 8.x we had this feature where we would join adjacent text notes as an optimization. This doesn't hold true for X anymore because we're not diffing directly against the dom anymore. In fact we noticed that it hurt performance in X which is why we removed it. Take the following example:

```jsx
// Preact 8.x
console.log(<div>foo{'bar'}</div>);
// Logs a structure like this:
//   div
//     text

// Preact X
console.log(<div>foo{'bar'}</div>);
// Logs a structure like this:
//   div
//     text
//     text
```

------

## Essentials

**Description:** Components are the heart of any Preact application. Learn how to create them and use them to compose UIs together

### Components

Components represent the basic building block in Preact. They are fundamental in making it easy to build complex UIs from little building blocks. They're also responsible for attaching state to our rendered output.

There are two kinds of components in Preact, which we'll talk about in this guide.



#### Functional Components

Functional components are plain functions that receive `props` as the first argument. The function name **must** start with an uppercase letter in order for them to work in JSX.

```jsx

import { render } from 'preact';

function MyComponent(props) {
	return <div>My name is {props.name}.</div>;
}

// Usage
const App = <MyComponent name="John Doe" />;

// Renders: <div>My name is John Doe.</div>
render(App, document.body);
```

> Note in earlier versions they were known as `"Stateless Components"`. This doesn't hold true anymore with the [hooks-addon](/guide/v10/hooks).

#### Class Components

Class components can have state and lifecycle methods. The latter are special methods, that will be called when a component is attached to the DOM or destroyed for example.

Here we have a simple class component called `<Clock>` that displays the current time:

```jsx

import { Component, render } from 'preact';

class Clock extends Component {
	constructor() {
		super();
		this.state = { time: Date.now() };
	}

	// Lifecycle: Called whenever our component is created
	componentDidMount() {
		// update time every second
		this.timer = setInterval(() => {
			this.setState({ time: Date.now() });
		}, 1000);
	}

	// Lifecycle: Called just before our component will be destroyed
	componentWillUnmount() {
		// stop when not renderable
		clearInterval(this.timer);
	}

	render() {
		let time = new Date(this.state.time).toLocaleTimeString();
		return <span>{time}</span>;
	}
}

render(<Clock />, document.getElementById('app'));
```

##### Lifecycle Methods

In order to have the clock's time update every second, we need to know when `<Clock>` gets mounted to the DOM. _If you've used HTML5 Custom Elements, this is similar to the `attachedCallback` and `detachedCallback` lifecycle methods._ Preact invokes the following lifecycle methods if they are defined for a Component:

| Lifecycle method                                           | When it gets called                                                                                         |
| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `componentWillMount()`                                     | (deprecated) before the component gets mounted to the DOM                                                   |
| `componentDidMount()`                                      | after the component gets mounted to the DOM                                                                 |
| `componentWillUnmount()`                                   | prior to removal from the DOM                                                                               |
| `componentWillReceiveProps(nextProps, nextContext)`        | before new props get accepted _(deprecated)_                                                                |
| `getDerivedStateFromProps(nextProps, prevState)`           | just before `shouldComponentUpdate`. Return object to update state or `null` to skip update. Use with care. |
| `shouldComponentUpdate(nextProps, nextState, nextContext)` | before `render()`. Return `false` to skip render                                                            |
| `componentWillUpdate(nextProps, nextState, nextContext)`   | before `render()` _(deprecated)_                                                                            |
| `getSnapshotBeforeUpdate(prevProps, prevState)`            | called just before `render()`. return value is passed to `componentDidUpdate`.                              |
| `componentDidUpdate(prevProps, prevState, snapshot)`       | after `render()`                                                                                            |

Here's a visual overview of how they relate to each other (originally posted in [a tweet](https://web.archive.org/web/20191118010106/https://twitter.com/dan_abramov/status/981712092611989509) by Dan Abramov):

![Diagram of component lifecycle methods](/guide/components-lifecycle-diagram.png)

##### Error Boundaries

An error boundary is a component that implements either `componentDidCatch()` or the static method `getDerivedStateFromError()` (or both). These are special methods that allow you to catch any errors that happen during rendering and are typically used to provide nicer error messages or other fallback content and save information for logging purposes. It's important to note that error boundaries cannot catch all errors and those thrown in event handlers or asynchronous code (like a `fetch()` call) need to be handled separately.

When an error is caught, we can use these methods to react to any errors and display a nice error message or any other fallback content.

```jsx

import { Component, render } from 'preact';

class ErrorBoundary extends Component {
	constructor() {
		super();
		this.state = { errored: false };
	}

	static getDerivedStateFromError(error) {
		return { errored: true };
	}

	componentDidCatch(error, errorInfo) {
		errorReportingService(error, errorInfo);
	}

	render(props, state) {
		if (state.errored) {
			return <p>Something went badly wrong</p>;
		}
		return props.children;
	}
}

render(<ErrorBoundary />, document.getElementById('app'));
```

#### Fragments

A `Fragment` allows you to return multiple elements at once. They solve the limitation of JSX where every "block" must have a single root element. You'll often encounter them in combination with lists, tables or with CSS flexbox where any intermediate element would otherwise affect styling.

```jsx

import { Fragment, render } from 'preact';

function TodoItems() {
	return (
		<Fragment>
			<li>A</li>
			<li>B</li>
			<li>C</li>
		</Fragment>
	);
}

const App = (
	<ul>
		<TodoItems />
		<li>D</li>
	</ul>
);

render(App, container);
// Renders:
// <ul>
//   <li>A</li>
//   <li>B</li>
//   <li>C</li>
//   <li>D</li>
// </ul>
```

Note that most modern transpilers allow you to use a shorter syntax for `Fragments`. The shorter one is a lot more common and is the one you'll typically encounter.

```jsx
// This:
const Foo = <Fragment>foo</Fragment>;
// ...is the same as this:
const Bar = <>foo</>;
```

You can also return arrays from your components:

```jsx
function Columns() {
	return [<td>Hello</td>, <td>World</td>];
}
```

Don't forget to add keys to `Fragments` if you create them in a loop:

```jsx
function Glossary(props) {
	return (
		<dl>
			{props.items.map(item => (
				// Without a key, Preact has to guess which elements have
				// changed when re-rendering.
				<Fragment key={item.id}>
					<dt>{item.term}</dt>
					<dd>{item.description}</dd>
				</Fragment>
			))}
		</dl>
	);
}
```

------

**Description:** Hooks in Preact allow you to compose behaviours together and re-use that logic in different components

### Hooks

The Hooks API is an alternative way to write components in Preact. Hooks allow you to compose state and side effects, reusing stateful logic much more easily than with class components.

If you've worked with class components in Preact for a while, you may be familiar with patterns like "render props" and "higher order components" that try to solve these challenges. These solutions have tended to make code harder to follow and more abstract. The hooks API makes it possible to neatly extract the logic for state and side effects, and also simplifies unit testing that logic independently from the components that rely on it.

Hooks can be used in any component, and avoid many pitfalls of the `this` keyword relied on by the class components API. Instead of accessing properties from the component instance, hooks rely on closures. This makes them value-bound and eliminates a number of stale data problems that can occur when dealing with asynchronous state updates.

There are two ways to import hooks: from `preact/hooks` or `preact/compat`.



#### Introduction

The easiest way to understand hooks is to compare them to equivalent class-based Components.

We'll use a simple counter component as our example, which renders a number and a button that increases it by one:

```jsx

import { render, Component } from 'preact';

class Counter extends Component {
	state = {
		value: 0
	};

	increment = () => {
		this.setState(prev => ({ value: prev.value + 1 }));
	};

	render(props, state) {
		return (
			<div>
				<p>Counter: {state.value}</p>
				<button onClick={this.increment}>Increment</button>
			</div>
		);
	}
}

render(<Counter />, document.getElementById('app'));
```

Now, here's an equivalent function component built with hooks:

```jsx

import { useState, useCallback } from 'preact/hooks';
import { render } from 'preact';

function Counter() {
	const [value, setValue] = useState(0);
	const increment = useCallback(() => {
		setValue(value + 1);
	}, [value]);

	return (
		<div>
			<p>Counter: {value}</p>
			<button onClick={increment}>Increment</button>
		</div>
	);
}

render(<Counter />, document.getElementById('app'));
```

At this point they seem pretty similar, however we can further simplify the hooks version.

Let's extract the counter logic into a custom hook, making it easily reusable across components:

```jsx

import { useState, useCallback } from 'preact/hooks';
import { render } from 'preact';

function useCounter() {
	const [value, setValue] = useState(0);
	const increment = useCallback(() => {
		setValue(value + 1);
	}, [value]);
	return { value, increment };
}

// First counter
function CounterA() {
	const { value, increment } = useCounter();
	return (
		<div>
			<p>Counter A: {value}</p>
			<button onClick={increment}>Increment</button>
		</div>
	);
}

// Second counter which renders a different output.
function CounterB() {
	const { value, increment } = useCounter();
	return (
		<div>
			<h1>Counter B: {value}</h1>
			<p>I'm a nice counter</p>
			<button onClick={increment}>Increment</button>
		</div>
	);
}

render(
	<div>
		<CounterA />
		<CounterB />
	</div>,
	document.getElementById('app')
);
```

Note that both `CounterA` and `CounterB` are completely independent of each other. They both use the `useCounter()` custom hook, but each has its own instance of that hook's associated state.

> Thinking this looks a little strange? You're not alone!
>
> It took many of us a while to grow accustomed to this approach.

#### The dependency argument

Many hooks accept an argument that can be used to limit when a hook should be updated. Preact inspects each value in a dependency array and checks to see if it has changed since the last time a hook was called. When the dependency argument is not specified, the hook is always executed.

In our `useCounter()` implementation above, we passed an array of dependencies to `useCallback()`:

```jsx
function useCounter() {
	const [value, setValue] = useState(0);
	const increment = useCallback(() => {
		setValue(value + 1);
	}, [value]); // <-- the dependency array
	return { value, increment };
}
```

Passing `value` here causes `useCallback` to return a new function reference whenever `value` changes.
This is necessary in order to avoid "stale closures", where the callback would always reference the first render's `value` variable from when it was created, causing `increment` to always set a value of `1`.

> This creates a new `increment` callback every time `value` changes.
> For performance reasons, it's often better to use a [callback](#usestate) to update state values rather than retaining the current value using dependencies.

#### Stateful hooks

Here we'll see how we can introduce stateful logic into functional components.

Prior to the introduction of hooks, class components were required anywhere state was needed.

##### useState

This hook accepts an argument, this will be the initial state. When
invoked this hook returns an array of two variables. The first being
the current state and the second being the setter for our state.

Our setter behaves similar to the setter of our classic state.
It accepts a value or a function with the currentState as argument.

When you call the setter and the state is different, it will trigger
a rerender starting from the component where that useState has been used.

```jsx

import { render } from 'preact';

import { useState } from 'preact/hooks';

const Counter = () => {
	const [count, setCount] = useState(0);
	const increment = () => setCount(count + 1);
	// You can also pass a callback to the setter
	const decrement = () => setCount(currentCount => currentCount - 1);

	return (
		<div>
			<p>Count: {count}</p>
			<button onClick={increment}>Increment</button>
			<button onClick={decrement}>Decrement</button>
		</div>
	);
};

render(<Counter />, document.getElementById('app'));
```

> When our initial state is expensive it's better to pass a function instead of a value.

##### useReducer

The `useReducer` hook has a close resemblance to [redux](https://redux.js.org/). Compared to [useState](#usestate) it's easier to use when you have complex state logic where the next state depends on the previous one.

```jsx

import { render } from 'preact';

import { useReducer } from 'preact/hooks';

const initialState = 0;
const reducer = (state, action) => {
	switch (action) {
		case 'increment':
			return state + 1;
		case 'decrement':
			return state - 1;
		case 'reset':
			return 0;
		default:
			throw new Error('Unexpected action');
	}
};

function Counter() {
	// Returns the current state and a dispatch function to
	// trigger an action
	const [count, dispatch] = useReducer(reducer, initialState);
	return (
		<div>
			{count}
			<button onClick={() => dispatch('increment')}>+1</button>
			<button onClick={() => dispatch('decrement')}>-1</button>
			<button onClick={() => dispatch('reset')}>reset</button>
		</div>
	);
}

render(<Counter />, document.getElementById('app'));
```

#### Memoization

In UI programming there is often some state or result that's expensive to calculate. Memoization can cache the results of that calculation allowing it to be reused when the same input is used.

##### useMemo

With the `useMemo` hook we can memoize the results of that computation and only recalculate it when one of the dependencies changes.

```jsx
const memoized = useMemo(
	() => expensive(a, b),
	// Only re-run the expensive function when any of these
	// dependencies change
	[a, b]
);
```

> Don't run any effectful code inside `useMemo`. Side-effects belong in `useEffect`.

##### useCallback

The `useCallback` hook can be used to ensure that the returned function will remain referentially equal for as long as no dependencies have changed. This can be used to optimize updates of child components when they rely on referential equality to skip updates (e.g. `shouldComponentUpdate`).

```jsx
const onClick = useCallback(() => console.log(a, b), [a, b]);
```

> Fun fact: `useCallback(fn, deps)` is equivalent to `useMemo(() => fn, deps)`.

#### Refs

**Ref**erences are stable, local values that persist across rerenders but don't cause rerenders themselves. See [Refs](/guide/v10/refs) for more information & examples.

##### useRef

To create a stable reference to a DOM node or a value that persists between renders, we can use the `useRef` hook. It works similarly to [createRef](/guide/v10/refs#createref).

```jsx

import { useRef } from 'preact/hooks';
import { render } from 'preact';

function Foo() {
	// Initialize useRef with an initial value of `null`
	const input = useRef(null);
	const onClick = () => input.current && input.current.focus();

	return (
		<>
			<input ref={input} />
			<button onClick={onClick}>Focus input</button>
		</>
	);
}

render(<Foo />, document.getElementById('app'));
```

> Be careful not to confuse `useRef` with `createRef`.

##### useImperativeHandle

To mutate a ref that is passed into a child component we can use the `useImperativeHandle` hook. It takes three arguments: the ref to mutate, a function to execute that will return the new ref value, and a dependency array to determine when to rerun.

```jsx

import { render } from 'preact';
import { useRef, useImperativeHandle, useState } from 'preact/hooks';

function MyInput({ inputRef }) {
	const ref = useRef(null);
	useImperativeHandle(
		inputRef,
		() => {
			return {
				// Only expose `.focus()`, don't give direct access to the DOM node
				focus() {
					ref.current.focus();
				}
			};
		},
		[]
	);

	return (
		<label>
			Name: <input ref={ref} />
		</label>
	);
}

function App() {
	const inputRef = useRef(null);

	const handleClick = () => {
		inputRef.current.focus();
	};

	return (
		<div>
			<MyInput inputRef={inputRef} />
			<button onClick={handleClick}>Click To Edit</button>
		</div>
	);
}

render(<App />, document.getElementById('app'));
```

#### useContext

To access context in a functional component we can use the `useContext` hook, without any higher-order or wrapper components. The first argument must be the context object that's created from a `createContext` call.

```jsx

import { render, createContext } from 'preact';
import { useContext } from 'preact/hooks';

const OtherComponent = props => props.children;

const Theme = createContext('light');

function DisplayTheme() {
	const theme = useContext(Theme);
	return <p>Active theme: {theme}</p>;
}

// ...later
function App() {
	return (
		<Theme.Provider value="light">
			<OtherComponent>
				<DisplayTheme />
			</OtherComponent>
		</Theme.Provider>
	);
}

render(<App />, document.getElementById('app'));
```

#### Side-Effects

Side-Effects are at the heart of many modern Apps. Whether you want to fetch some data from an API or trigger an effect on the document, you'll find that the `useEffect` fits nearly all your needs. It's one of the main advantages of the hooks API, that it reshapes your mind into thinking in effects instead of a component's lifecycle.

##### useEffect

As the name implies, `useEffect` is the main way to trigger various side-effects. You can even return a cleanup function from your effect if one is needed.

```jsx
useEffect(() => {
	// Trigger your effect
	return () => {
		// Optional: Any cleanup code
	};
}, []);
```

We'll start with a `Title` component which should reflect the title to the document, so that we can see it in the address bar of our tab in our browser.

```jsx
function PageTitle(props) {
	useEffect(() => {
		document.title = props.title;
	}, [props.title]);

	return <h1>{props.title}</h1>;
}
```

The first argument to `useEffect` is an argument-less callback that triggers the effect. In our case we only want to trigger it, when the title really has changed. There'd be no point in updating it when it stayed the same. That's why we're using the second argument to specify our [dependency-array](#the-dependency-argument).

But sometimes we have a more complex use case. Think of a component which needs to subscribe to some data when it mounts and needs to unsubscribe when it unmounts. This can be accomplished with `useEffect` too. To run any cleanup code we just need to return a function in our callback.

```jsx

import { useState, useEffect } from 'preact/hooks';
import { render } from 'preact';

// Component that will always display the current window width
function WindowWidth(props) {
	const [width, setWidth] = useState(0);

	function onResize() {
		setWidth(window.innerWidth);
	}

	useEffect(() => {
		window.addEventListener('resize', onResize);
		return () => window.removeEventListener('resize', onResize);
	}, []);

	return <p>Window width: {width}</p>;
}

render(<WindowWidth />, document.getElementById('app'));
```

> The cleanup function is optional. If you don't need to run any cleanup code, you don't need to return anything in the callback that's passed to `useEffect`.

##### useLayoutEffect

Similar to [`useEffect`](#useeffect), `useLayoutEffect` is used to trigger side-effects but it will do so as soon as the component is diffed and before the browser has a chance to repaint. Commonly used for measuring DOM elements, this allows you to avoid flickering or pop-in that may occur if you use `useEffect` for such tasks.

```jsx
import { useLayoutEffect, useRef } from 'preact/hooks';

function App() {
	const hintRef = useRef(null);

	useLayoutEffect(() => {
		const hintWidth = hintRef.current.getBoundingClientRect().width;

		// We might use this width to position and center the hint on the screen, like so:
		hintRef.current.style.left = `${(window.innerWidth - hintWidth) / 2}px`;
	}, []);

	return (
		<div style="display: inline; position: absolute" ref={hintRef}>
			<p>This is a hint</p>
		</div>
	);
}
```

##### useErrorBoundary

Whenever a child component throws an error you can use this hook to catch it and display a custom error UI to the user.

```jsx
// error = The error that was caught or `undefined` if nothing errored.
// resetError = Call this function to mark an error as resolved. It's
//   up to your app to decide what that means and if it is possible
//   to recover from errors.
const [error, resetError] = useErrorBoundary();
```

For monitoring purposes it's often incredibly useful to notify a service of any errors. For that we can leverage an optional callback and pass that as the first argument to `useErrorBoundary`.

```jsx
const [error] = useErrorBoundary(error => callMyApi(error.message));
```

A full usage example may look like this:

```jsx
const App = props => {
	const [error, resetError] = useErrorBoundary(error =>
		callMyApi(error.message)
	);

	// Display a nice error message
	if (error) {
		return (
			<div>
				<p>{error.message}</p>
				<button onClick={resetError}>Try again</button>
			</div>
		);
	} else {
		return <div>{props.children}</div>;
	}
};
```

> If you've been using the class based component API in the past, then this hook is essentially an alternative to the [componentDidCatch](/guide/v10/whats-new/#componentdidcatch) lifecycle method.
> This hook was introduced with Preact 10.2.0.

#### Utility hooks

##### useId

This hook will generate a unique identifier for each invocation and guarantees that these will be consistent when rendering both [on the server](/guide/v10/server-side-rendering) and the client. A common use case for consistent IDs are forms, where `<label>`-elements use the [`for`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/label#attr-for) attribute to associate them with a specific `<input>`-element. The `useId` hook isn't tied to just forms though and can be used whenever you need a unique ID.

> To make the hook consistent you will need to use Preact on both the server
> as well as on the client.

A full usage example may look like this:

```jsx
const App = props => {
  const mainId = useId();
  const inputId = useId();

  useLayoutEffect(() => {
    document.getElementById(inputId).focus()
  }, [])

  // Display an input with a unique ID.
  return (
    <main id={mainId}>
      <input id={inputId}>
    </main>
  )
};
```

> This hook was introduced with Preact 10.11.0 and needs preact-render-to-string 5.2.4.

##### useDebugValue

Displays a custom label for use in the Preact DevTools browser extension. Useful for custom hooks to provide additional context about the state or value they represent.

```jsx
import { useDebugValue, useState } from 'preact/hooks';

function useCount() {
	const [count, setCount] = useState(0);
	useDebugValue(count > 0 ? 'Positive' : 'Negative');
	return [count, setCount];
}
```

In your devtools, this will display as `useCount: "Positive"` or `useCount: "Negative"`, whereas previously it would've been just `useCount`.

Optionally, you can also pass a function as the second argument to `useDebugValue` for use as the "formatter".

```jsx
import { useDebugValue, useState } from 'preact/hooks';

function useCount() {
	const [count, setCount] = useState(0);
	useDebugValue(count, c => `Count: ${c}`);
	return [count, setCount];
}
```

#### Compat-specific hooks

We offer some additional hooks only through the `preact/compat` package, as they are either stubbed-out implementations or are not part of the essential hooks API.

##### useSyncExternalStore

Allows you to subscribe to an external data source, such as a global state management library, browser APIs, or any other external (to Preact) data source.

```jsx
import { useSyncExternalStore } from 'preact/compat';

function subscribe(cb) {
	addEventListener('scroll', cb);
	return () => removeEventListener('scroll', cb);
}

function App() {
	const scrollY = useSyncExternalStore(subscribe, () => window.scrollY);
}
```

##### useDeferredValue

Stubbed-out implementation, immediately returns the value as Preact does not support concurrent rendering.

```jsx
import { useDeferredValue } from 'preact/compat';

function App() {
	const deferredValue = useDeferredValue('Hello, World!');
}
```

##### useTransition

Stubbed-out implementation as Preact does not support concurrent rendering.

```jsx
import { useTransition } from 'preact/compat';

function App() {
	// `isPending` will always be `false`
	const [isPending, startTransition] = useTransition();

	const handleClick = () => {
		// Immediately executes the callback, it's a no-op.
		startTransition(() => {
			// Transition code here
		});
	};
}
```

##### useInsertionEffect

Stubbed-out implementation, matches [`useLayoutEffect`](#uselayouteffect) in functionality.

```jsx
import { useInsertionEffect } from 'preact/compat';

function App() {
	useInsertionEffect(() => {
		// Effect code here
	}, [dependencies]);
}
```

------

**Description:** Composable reactive state with automatic rendering

### Signals

Signals are reactive primitives for managing application state.

What makes Signals unique is that state changes automatically update components and UI in the most efficient way possible. Automatic state binding and dependency tracking allows Signals to provide excellent ergonomics and productivity while eliminating the most common state management footguns.

Signals are effective in applications of any size, with ergonomics that speed up the development of small apps, and performance characteristics that ensure apps of any size are fast by default.

---

**Important**

This guide will go over using Signals in Preact, and while this is largely applicable to both the Core and React libraries, there will be some usage differences. The best references for their usage is in their respective docs: [`@preact/signals-core`](https://github.com/preactjs/signals), [`@preact/signals-react`](https://github.com/preactjs/signals/tree/main/packages/react)



#### Introduction

Much of the pain of state management in JavaScript is reacting to changes for a given value, because values are not directly observable. Solutions typically work around this by storing values in a variable and continuously checking to see if they have changed, which is cumbersome and not ideal for performance. Ideally, we want a way to express a value that tells us when it changes. That's what Signals do.

At its core, a signal is an object with a `.value` property that holds a value. This has an important characteristic: a signal's value can change, but the signal itself always stays the same:

```js

import { signal } from '@preact/signals';

const count = signal(0);

// Read a signal’s value by accessing .value:
console.log(count.value); // 0

// Update a signal’s value:
count.value += 1;

// The signal's value has changed:
console.log(count.value); // 1
```

In Preact, when a signal is passed down through a tree as props or context, we're only passing around references to the signal. The signal can be updated without re-rendering any components, since components see the signal and not its value. This lets us skip all of the expensive rendering work and jump immediately to any components in the tree that actually access the signal's `.value` property.

Signals have a second important characteristic, which is that they track when their value is accessed and when it is updated. In Preact, accessing a signal's `.value` property from within a component automatically re-renders the component when that signal's value changes.

```jsx

import { render } from 'preact';

import { signal } from '@preact/signals';

// Create a signal that can be subscribed to:
const count = signal(0);

function Counter() {
	// Accessing .value in a component automatically re-renders when it changes:
	const value = count.value;

	const increment = () => {
		// A signal is updated by assigning to the `.value` property:
		count.value++;
	};

	return (
		<div>
			<p>Count: {value}</p>
			<button onClick={increment}>click me</button>
		</div>
	);
}

render(<Counter />, document.getElementById('app'));
```

Finally, Signals are deeply integrated into Preact to provide the best possible performance and ergonomics. In the example above, we accessed `count.value` to retrieve the current value of the `count` signal, however this is unnecessary. Instead, we can let Preact do all of the work for us by using the `count` signal directly in JSX:

```jsx

import { render } from 'preact';

import { signal } from '@preact/signals';

const count = signal(0);

function Counter() {
	return (
		<div>
			<p>Count: {count}</p>
			<button onClick={() => count.value++}>click me</button>
		</div>
	);
}

render(<Counter />, document.getElementById('app'));
```

#### Installation

Signals can be installed by adding the `@preact/signals` package to your project:

```bash
npm install @preact/signals
```

Once installed via your package manager of choice, you're ready to import it in your app.

#### Usage Example

Let's use signals in a real world scenario. We're going to build a todo list app, where you can add and remove items in a todo list. We'll start by modeling the state. We're going to need a signal that holds a list of todos first, which we can represent with an `Array`:

```jsx
import { signal } from '@preact/signals';

const todos = signal([{ text: 'Buy groceries' }, { text: 'Walk the dog' }]);
```

To let the user enter text for a new todo item, we'll need one more signal that we'll connect up to an `<input>` element shortly. For now, we can use this signal already to create a function that adds a todo item to our list. Remember, we can update a signal's value by assigning to its `.value` property:

```jsx
// We'll use this for our input later
const text = signal('');

function addTodo() {
	todos.value = [...todos.value, { text: text.value }];
	text.value = ''; // Clear input value on add
}
```

> :bulb: Tip: A signal will only update if you assign a new value to it. If the value you assign to a signal is equal to its current value, it won't update.
>
> ```js
> const count = signal(0);
>
> count.value = 0; // does nothing - value is already 0
>
> count.value = 1; // updates - value is different
> ```

Let's check if our logic is correct so far. When we update the `text` signal and call `addTodo()`, we should see a new item being added to the `todos` signal. We can simulate this scenario by calling these functions directly - no need for a user interface yet!

```jsx

import { signal } from '@preact/signals';

const todos = signal([{ text: 'Buy groceries' }, { text: 'Walk the dog' }]);

const text = signal('');

function addTodo() {
	todos.value = [...todos.value, { text: text.value }];
	text.value = ''; // Reset input value on add
}

// Check if our logic works
console.log(todos.value);
// Logs: [{text: "Buy groceries"}, {text: "Walk the dog"}]

// Simulate adding a new todo
text.value = 'Tidy up';
addTodo();

// Check that it added the new item and cleared the `text` signal:
console.log(todos.value);
// Logs: [{text: "Buy groceries"}, {text: "Walk the dog"}, {text: "Tidy up"}]

console.log(text.value); // Logs: ""
```

The last feature we'd like to add is the ability to remove a todo item from the list. For this, we'll add a function that deletes a given todo item from the todos array:

```jsx
function removeTodo(todo) {
	todos.value = todos.value.filter(t => t !== todo);
}
```

#### Building the UI

Now that we've modeled our application's state, it's time to wire in up to a nice UI that users can interact with.

```jsx
function TodoList() {
	const onInput = event => (text.value = event.currentTarget.value);

	return (
		<>
			<input value={text.value} onInput={onInput} />
			<button onClick={addTodo}>Add</button>
			<ul>
				{todos.value.map(todo => (
					<li>
						{todo.text} <button onClick={() => removeTodo(todo)}>❌</button>
					</li>
				))}
			</ul>
		</>
	);
}
```

And with that we have a fully working todo app! You can try out the full app [over here](/repl?example=todo-signals) :tada:

#### Deriving state via computed signals

Let's add one more feature to our todo app: each todo item can be checked off as completed, and we'll show the user the number of items they've completed. To do that we'll import the [`computed(fn)`](#computedfn) function, which lets us create a new signal that is computed based on the values of other signals. The returned computed signal is read-only, and its value is automatically updated when any signals accessed from within the callback function change.

```jsx

import { signal, computed } from '@preact/signals';

const todos = signal([
	{ text: 'Buy groceries', completed: true },
	{ text: 'Walk the dog', completed: false }
]);

// create a signal computed from other signals
const completed = computed(() => {
	// When `todos` changes, this re-runs automatically:
	return todos.value.filter(todo => todo.completed).length;
});

// Logs: 1, because one todo is marked as being completed
console.log(completed.value);
```

Our simple todo list app doesn't need many computed signals, but more complex apps tend to rely on computed() to avoid duplicating state in multiple places.

> :bulb: Tip: Deriving as much state as possible ensures that your state always has a single source of truth. It is a key principle of signals. This makes debugging a lot easier in case there is a flaw in application logic later on, as there are less places to worry about.

#### Managing global app state

Up until now, we've only created signals outside the component tree. This is fine for a small app like a todo list, but for larger and more complex apps this can make testing difficult. Tests typically involve changing values in your app state to reproduce a certain scenario, then passing that state to components and asserting on the rendered HTML. To do this, we can extract our todo list state into a function:

```jsx
function createAppState() {
	const todos = signal([]);

	const completed = computed(() => {
		return todos.value.filter(todo => todo.completed).length;
	});

	return { todos, completed };
}
```

> :bulb: Tip: Notice that we're consciously not including the `addTodo()` and `removeTodo(todo)` functions here. Separating data from functions that modify it often helps simplify application architecture. For more details, check out [data-oriented design](https://en.wikipedia.org/wiki/Data-oriented_design).

We can now pass our todo application state as a prop when rendering:

```jsx
const state = createAppState();

// ...later:
<TodoList state={state} />;
```

This works in our todo list app because the state is global, however larger apps typically end up with multiple components that require access to the same pieces of state. This usually involves "lifting state up" to a common shared ancestor component. To avoid passing state manually through each component via props, the state can be placed into [Context](/guide/v10/context) so any component in the tree can access it. Here is a quick example of how that typically looks:

```jsx
import { createContext } from 'preact';
import { useContext } from 'preact/hooks';
import { createAppState } from './my-app-state';

const AppState = createContext();

render(
	<AppState.Provider value={createAppState()}>
		<App />
	</AppState.Provider>
);

// ...later when you need access to your app state
function App() {
	const state = useContext(AppState);
	return <p>{state.completed}</p>;
}
```

If you want to learn more about how context works, head over to the [Context documentation](/guide/v10/context).

#### Local state with signals

The majority of application state ends up being passed around using props and context. However, there are many scenarios where components have their own internal state that is specific to that component. Since there is no reason for this state to live as part of the app's global business logic, it should be confined to the component that needs it. In these scenarios, we can create signals as well as computed signals directly within components using the `useSignal()` and `useComputed()` hooks:

```jsx
import { useSignal, useComputed } from '@preact/signals';

function Counter() {
	const count = useSignal(0);
	const double = useComputed(() => count.value * 2);

	return (
		<div>
			<p>
				{count} x 2 = {double}
			</p>
			<button onClick={() => count.value++}>click me</button>
		</div>
	);
}
```

Those two hooks are thin wrappers around [`signal()`](#signalinitialvalue) and [`computed()`](#computedfn) that construct a signal the first time a component runs, and simply use that same signal on subsequent renders.

> :bulb: Behind the scenes, this is the implementation:
>
> ```js
> function useSignal(value) {
> 	return useMemo(() => signal(value), []);
> }
> ```

#### Advanced signals usage

The topics we've covered so far are all you need to get going. The following section is aimed at readers who want to benefit even more by modeling their application state entirely using signals.

##### Reacting to signals outside of components

When working with signals outside of the component tree, you may have noticed that computed signals don't re-compute unless you actively read their value. This is because signals are lazy by default: they only compute new values when their value has been accessed.

```js
const count = signal(0);
const double = computed(() => count.value * 2);

// Despite updating the `count` signal on which the `double` signal depends,
// `double` does not yet update because nothing has used its value.
count.value = 1;

// Reading the value of `double` triggers it to be re-computed:
console.log(double.value); // Logs: 2
```

This poses a question: how can we subscribe to signals outside of the component tree? Perhaps we want to log something to the console whenever a signal's value changes, or persist state to [LocalStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage).

To run arbitrary code in response to signal changes, we can use [`effect(fn)`](#effectfn). Similar to computed signals, effects track which signals are accessed and re-run their callback when those signals change. Unlike computed signals, [`effect()`](#effectfn) does not return a signal - it's the end of a sequence of changes.

```js
import { signal, computed, effect } from '@preact/signals';

const name = signal('Jane');
const surname = signal('Doe');
const fullName = computed(() => `${name.value} ${surname.value}`);

// Logs name every time it changes:
effect(() => console.log(fullName.value));
// Logs: "Jane Doe"

// Updating `name` updates `fullName`, which triggers the effect again:
name.value = 'John';
// Logs: "John Doe"
```

Optionally, you can return a cleanup function from the callback provided to [`effect()`](#effectfn) that will be run before the next update takes place. This allows you to "clean up" the side effect and potentially reset any state for the subsequent trigger of the callback.

```js
effect(() => {
	Chat.connect(username.value);

	return () => Chat.disconnect(username.value);
});
```

You can destroy an effect and unsubscribe from all signals it accessed by calling the returned function.

```js
import { signal, effect } from '@preact/signals';

const name = signal('Jane');
const surname = signal('Doe');
const fullName = computed(() => name.value + ' ' + surname.value);

const dispose = effect(() => console.log(fullName.value));
// Logs: "Jane Doe"

// Destroy effect and subscriptions:
dispose();

// Updating `name` does not run the effect because it has been disposed.
// It also doesn't re-compute `fullName` now that nothing is observing it.
name.value = 'John';
```

> :bulb: Tip: Don't forget to clean up effects if you're using them extensively. Otherwise your app will consume more memory than needed.

#### Reading signals without subscribing to them

On the rare occasion that you need to write to a signal inside [`effect(fn)`](#effectfn), but don't want the effect to re-run when that signal changes,
you can use `.peek()` to get the signal's current value without subscribing.

```js
const delta = signal(0);
const count = signal(0);

effect(() => {
	// Update `count` without subscribing to `count`:
	count.value = count.peek() + delta.value;
});

// Setting `delta` reruns the effect:
delta.value = 1;

// This won't rerun the effect because it didn't access `.value`:
count.value = 10;
```

> :bulb: Tip: The scenarios in which you don't want to subscribe to a signal are rare. In most cases you want your effect to subscribe to all signals. Only use `.peek()` when you really need to.

As an alternative to `.peek()`, we have the `untracked` function which receives a function as an argument and returns the outcome of the function. In `untracked` you can
reference any signal with `.value` without creating a subscription. This can come in handy when you have a reusable function that accesses `.value` or you need to access
more than 1 signal.

```js
const delta = signal(0);
const count = signal(0);

effect(() => {
	// Update `count` without subscribing to `count` or `delta`:
	count.value = untracked(() => {
		return count.value + delta.value;
	});
});
```

#### Combining multiple updates into one

Remember the `addTodo()` function we used earlier in our todo app? Here is a refresher on what it looked like:

```js
const todos = signal([]);
const text = signal('');

function addTodo() {
	todos.value = [...todos.value, { text: text.value }];
	text.value = '';
}
```

Notice that the function triggers two separate updates: one when setting `todos.value` and the other when setting the value of `text`. This can sometimes be undesirable and warrant combining both updates into one, for performance or other reasons. The [`batch(fn)`](#batchfn) function can be used to combine multiple value updates into one "commit" at the end of the callback:

```js
function addTodo() {
	batch(() => {
		todos.value = [...todos.value, { text: text.value }];
		text.value = '';
	});
}
```

Accessing a signal that has been modified within a batch will reflect its updated value. Accessing a computed signal that has been invalidated by another signal within a batch will re-compute only the necessary dependencies to return an up-to-date value for that computed signal. Any other invalidated signals remain unaffected and are only updated at the end of the batch callback.

```js

import { signal, computed, effect, batch } from '@preact/signals';

const count = signal(0);
const double = computed(() => count.value * 2);
const triple = computed(() => count.value * 3);

effect(() => console.log(double.value, triple.value));

batch(() => {
	// set `count`, invalidating `double` and `triple`:
	count.value = 1;

	// Despite being batched, `double` reflects the new computed value.
	// However, `triple` will only update once the callback completes.
	console.log(double.value); // Logs: 2
});
```

> :bulb: Tip: Batches can also be nested, in which case batched updates are flushed only after the outermost batch callback has completed.

##### Rendering optimizations

With signals we can bypass Virtual DOM rendering and bind signal changes directly to DOM mutations. If you pass a signal into JSX in a text position, it will render as text and automatically update in-place without Virtual DOM diffing:

```jsx
const count = signal(0);

function Unoptimized() {
	// Re-renders the component when `count` changes:
	return <p>{count.value}</p>;
}

function Optimized() {
	// Text automatically updates without re-rendering the component:
	return <p>{count}</p>;
}
```

To enable this optimization, pass the signal into JSX instead of accessing its `.value` property.

A similar rendering optimization is also supported when passing signals as props on DOM elements.

#### API

This section is an overview of the signals API. It's aimed to be a quick reference for folks who already know how to use signals and need a reminder of what's available.

##### signal(initialValue)

Creates a new signal with the given argument as its initial value:

```js
const count = signal(0);
```

The returned signal has a `.value` property that can be get or set to read and write its value. To read from a signal without subscribing to it, use `signal.peek()`.

###### useSignal(initialValue)

When creating signals within a component, use the hook variant: `useSignal(initialValue)`. It functions similarly to `signal()` but is memoized to ensure that the same signal instance is used across renders of the component.

```jsx
function MyComponent() {
	const count = useSignal(0);
}
```

##### computed(fn)

Creates a new signal that is computed based on the values of other signals. The returned computed signal is read-only, and its value is automatically updated when any signals accessed from within the callback function change.

```js
const name = signal('Jane');
const surname = signal('Doe');

const fullName = computed(() => `${name.value} ${surname.value}`);
```

###### useComputed(fn)

When creating computed signals within a component, use the hook variant: `useComputed(fn)`.

```jsx
function MyComponent() {
	const name = useSignal('Jane');
	const surname = useSignal('Doe');

	const fullName = useComputed(() => `${name.value} ${surname.value}`);
}
```

##### effect(fn)

To run arbitrary code in response to signal changes, we can use `effect(fn)`. Similar to computed signals, effects track which signals are accessed and re-run their callback when those signals change. If the callback returns a function, this function will be run before the next value update. Unlike computed signals, `effect()` does not return a signal - it's the end of a sequence of changes.

```js
const name = signal('Jane');

// Log to console when `name` changes:
effect(() => console.log('Hello', name.value));
// Logs: "Hello Jane"

name.value = 'John';
// Logs: "Hello John"
```

###### useSignalEffect(fn)

When responding to signal changes within a component, use the hook variant: `useSignalEffect(fn)`.

```jsx
function MyComponent() {
	const name = useSignal('Jane');

	// Log to console when `name` changes:
	useSignalEffect(() => console.log('Hello', name.value));
}
```

##### batch(fn)

The `batch(fn)` function can be used to combine multiple value updates into one "commit" at the end of the provided callback. Batches can be nested and changes are only flushed once the outermost batch callback completes. Accessing a signal that has been modified within a batch will reflect its updated value.

```js
const name = signal('Jane');
const surname = signal('Doe');

// Combine both writes into one update
batch(() => {
	name.value = 'John';
	surname.value = 'Smith';
});
```

##### untracked(fn)

The `untracked(fn)` function can be used to access the value of several signals without subscribing to them.

```js
const name = signal('Jane');
const surname = signal('Doe');

effect(() => {
	untracked(() => {
		console.log(`${name.value} ${surname.value}`);
	});
});
```

#### Utility Components and Hooks

As of v2.1.0, the `@preact/signals/utils` package provides additional utility components and hooks to make working with signals even easier.

##### Show Component

The `<Show>` component provides a declarative way to conditionally render content based on a signal's value.

```jsx
import { signal } from '@preact/signals';
import { Show } from '@preact/signals/utils';

const isVisible = signal(false);

function App() {
	return (
		<Show when={isVisible} fallback={<p>Nothing to see here</p>}>
			<p>Now you see me!</p>
		</Show>
	);
}

// You can also use a function to access the value
function App() {
	return <Show when={isVisible}>{value => <p>The value is {value}</p>}</Show>;
}
```

##### For Component

The `<For>` component helps you render lists from signal arrays with automatic caching of rendered items.

```jsx
import { signal } from '@preact/signals';
import { For } from '@preact/signals/utils';

const items = signal(['A', 'B', 'C']);

function App() {
	return (
		<For each={items} fallback={<p>No items</p>}>
			{(item, index) => <div key={index}>Item: {item}</div>}
		</For>
	);
}
```

##### Additional Hooks

###### useLiveSignal(signal)

The `useLiveSignal(signal)` hook allows you to create a local signal that stays synchronized with an external signal.

```jsx
import { signal } from '@preact/signals';
import { useLiveSignal } from '@preact/signals/utils';

const external = signal(0);

function Component() {
	const local = useLiveSignal(external);
	// local will automatically update when external changes
}
```

###### useSignalRef(initialValue)

The `useSignalRef(initialValue)` hook creates a signal that behaves like a React ref with a `.current` property.

```jsx
import { useSignalEffect } from '@preact/signals';
import { useSignalRef } from '@preact/signals/utils';

function Component() {
	const ref = useSignalRef(null);

	useSignalEffect(() => {
		if (ref.current) {
			console.log('Ref has been set to:', ref.current);
		}
	});

	return (
		<div ref={ref}>
			The ref has been attached to a {ref.current?.tagName} element.
		</div>
	);
}
```

------

**Description:** Forms and form controls allow you to collect user input in your application and is a fundamental building block of most web applications

### Forms

Forms in Preact work in the same way as they do in HTML & JS: you render controls, attach event listeners, and submit information.



#### Basic Form Controls

Often you'll want to collect user input in your application, and this is where `<input>`, `<textarea>`, and `<select>` elements come in. These elements are the common building blocks of forms in HTML and Preact.

##### Input (text)

To get started, we'll create a simple text input field that will update a state value as the user types. We'll use the `onInput` event to listen for changes to the input field's value and update the state per-keystroke. This state value is then rendered in a `<p>` element, so we can see the results.

<tab-group tabstring="Classes, Hooks">

```jsx

import { render, Component } from 'preact';

class BasicInput extends Component {
	state = { name: '' };

	onInput = e => this.setState({ name: e.currentTarget.value });

	render(_, { name }) {
		return (
			<div class="form-example">
				<label>
					Name: <input onInput={this.onInput} />
				</label>
				<p>Hello {name}</p>
			</div>
		);
	}
}

render(<BasicInput />, document.getElementById('app'));
```

```jsx

import { render } from 'preact';
import { useState } from 'preact/hooks';

function BasicInput() {
	const [name, setName] = useState('');

	return (
		<div class="form-example">
			<label>
				Name: <input onInput={e => setName(e.currentTarget.value)} />
			</label>
			<p>Hello {name}</p>
		</div>
	);
}

render(<BasicInput />, document.getElementById('app'));
```

</tab-group>

##### Input (checkbox & radio)

<tab-group tabstring="Classes, Hooks">

```jsx

import { render, Component } from 'preact';

class BasicRadioButton extends Component {
	state = {
		allowContact: false,
		contactMethod: ''
	};

	toggleContact = () =>
		this.setState({ allowContact: !this.state.allowContact });
	setRadioValue = e => this.setState({ contactMethod: e.currentTarget.value });

	render(_, { allowContact }) {
		return (
			<div class="form-example">
				<label>
					Allow contact: <input type="checkbox" onClick={this.toggleContact} />
				</label>
				<label>
					Phone:{' '}
					<input
						type="radio"
						name="contact"
						value="phone"
						onClick={this.setRadioValue}
						disabled={!allowContact}
					/>
				</label>
				<label>
					Email:{' '}
					<input
						type="radio"
						name="contact"
						value="email"
						onClick={this.setRadioValue}
						disabled={!allowContact}
					/>
				</label>
				<label>
					Mail:{' '}
					<input
						type="radio"
						name="contact"
						value="mail"
						onClick={this.setRadioValue}
						disabled={!allowContact}
					/>
				</label>
				<p>
					You {allowContact ? 'have allowed' : 'have not allowed'} contact{' '}
					{allowContact && ` via ${this.state.contactMethod}`}
				</p>
			</div>
		);
	}
}

render(<BasicRadioButton />, document.getElementById('app'));
```

```jsx

import { render } from 'preact';
import { useState } from 'preact/hooks';

function BasicRadioButton() {
	const [allowContact, setAllowContact] = useState(false);
	const [contactMethod, setContactMethod] = useState('');

	const toggleContact = () => setAllowContact(!allowContact);
	const setRadioValue = e => setContactMethod(e.currentTarget.value);

	return (
		<div class="form-example">
			<label>
				Allow contact: <input type="checkbox" onClick={toggleContact} />
			</label>
			<label>
				Phone:{' '}
				<input
					type="radio"
					name="contact"
					value="phone"
					onClick={setRadioValue}
					disabled={!allowContact}
				/>
			</label>
			<label>
				Email:{' '}
				<input
					type="radio"
					name="contact"
					value="email"
					onClick={setRadioValue}
					disabled={!allowContact}
				/>
			</label>
			<label>
				Mail:{' '}
				<input
					type="radio"
					name="contact"
					value="mail"
					onClick={setRadioValue}
					disabled={!allowContact}
				/>
			</label>
			<p>
				You {allowContact ? 'have allowed' : 'have not allowed'} contact{' '}
				{allowContact && ` via ${contactMethod}`}
			</p>
		</div>
	);
}

render(<BasicRadioButton />, document.getElementById('app'));
```

</tab-group>

##### Select

<tab-group tabstring="Classes, Hooks">

```jsx

import { render, Component } from 'preact';

class MySelect extends Component {
	state = { value: '' };

	onChange = e => {
		this.setState({ value: e.currentTarget.value });
	};

	render(_, { value }) {
		return (
			<div class="form-example">
				<select onChange={this.onChange}>
					<option value="A">A</option>
					<option value="B">B</option>
					<option value="C">C</option>
				</select>
				<p>You selected: {value}</p>
			</div>
		);
	}
}

render(<MySelect />, document.getElementById('app'));
```

```jsx

import { render } from 'preact';
import { useState } from 'preact/hooks';

function MySelect() {
	const [value, setValue] = useState('');

	return (
		<div class="form-example">
			<select onChange={e => setValue(e.currentTarget.value)}>
				<option value="A">A</option>
				<option value="B">B</option>
				<option value="C">C</option>
			</select>
			<p>You selected: {value}</p>
		</form>
	);
}

render(<MySelect />, document.getElementById('app'));
```

</tab-group>

#### Basic Forms

Whilst bare inputs are useful and you can get far with them, often we'll see our inputs grow into _forms_ that are capable of grouping multiple controls together. To help manage this, we turn to the `<form>` element.

To demonstrate, we'll create a new `<form>` element that contains two `<input>` fields: one for a user's first name and one for their last name. We'll use the `onSubmit` event to listen for the form submission and update the state with the user's full name.

<tab-group tabstring="Classes, Hooks">

```jsx

import { render, Component } from 'preact';

class FullNameForm extends Component {
	state = { fullName: '' };

	onSubmit = e => {
		e.preventDefault();
		const formData = new FormData(e.currentTarget);
		this.setState({
			fullName: formData.get('firstName') + ' ' + formData.get('lastName')
		});
		e.currentTarget.reset(); // Clear the inputs to prepare for the next submission
	};

	render(_, { fullName }) {
		return (
			<div class="form-example">
				<form onSubmit={this.onSubmit}>
					<label>
						First Name: <input name="firstName" />
					</label>
					<label>
						Last Name: <input name="lastName" />
					</label>
					<button>Submit</button>
				</form>
				{fullName && <p>Hello {fullName}</p>}
			</div>
		);
	}
}

render(<FullNameForm />, document.getElementById('app'));
```

```jsx

import { render } from 'preact';
import { useState } from 'preact/hooks';

function FullNameForm() {
	const [fullName, setFullName] = useState('');

	const onSubmit = e => {
		e.preventDefault();
		const formData = new FormData(e.currentTarget);
		setFullName(formData.get('firstName') + ' ' + formData.get('lastName'));
		e.currentTarget.reset(); // Clear the inputs to prepare for the next submission
	};

	return (
		<div class="form-example">
			<form onSubmit={onSubmit}>
				<label>
					First Name: <input name="firstName" />
				</label>
				<label>
					Last Name: <input name="lastName" />
				</label>
				<button>Submit</button>
			</form>
			{fullName && <p>Hello {fullName}</p>}
		</div>
	);
}

render(<FullNameForm />, document.getElementById('app'));
```

</tab-group>

> **Note**: Whilst it's quite common to see React & Preact forms that link every input field to component state, it's often unnecessary and can get unwieldy. As a very loose rule of thumb, you should prefer using `onSubmit` and the [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) API in most cases, using component state only when you need to. This reduces the complexity of your components and may skip unnecessary rerenders.

#### Controlled & Uncontrolled Components

When talking about form controls you may encounter the terms "Controlled Component" and "Uncontrolled Component". These terms refer to whether or not the form control value is explicitly managed by the component. Generally, you should try to use _Uncontrolled_ Components whenever possible, the DOM is fully capable of handling `<input>`'s state:

```jsx
// Uncontrolled, because Preact doesn't set the value
<input onInput={myEventHandler} />
```

However, there are situations in which you might need to exert tighter control over the input value, in which case, _Controlled_ Components can be used.

```jsx
// Controlled, because Preact sets the value
<input value={myValue} onInput={myEventHandler} />
```

Preact has a known issue with controlled components: rerenders are required for Preact to exert control over input values. This means that if your event handler doesn't update state or trigger a rerender in some fashion, the input value will not be controlled, sometimes becoming out-of-sync with component state.

An example of one of these problematic situations is as such: say you have an input field that should be limited to 3 characters. You may have an event handler like the following:

```js
const onInput = e => {
	if (e.currentTarget.value.length <= 3) {
		setValue(e.currentTarget.value);
	}
};
```

The problem with this is in the cases where the input fails that condition: because we don't run `setValue`, the component doesn't rerender, and because the component doesn't rerender, the input value is not correctly controlled. However, even if we did add a `else { setValue(value) }` to that handler, Preact is smart enough to detect when the value hasn't changed and so it will not rerender the component. This leaves us with [`refs`](/guide/v10/refs) to bridge the gap between the DOM state and Preact's state.

> For more information on controlled components in Preact, see [Controlled Inputs](https://www.jovidecroock.com/blog/controlled-inputs) by Jovi De Croock.

Here's an example of how you might use a controlled component to limit the number of characters in an input field:

<tab-group tabstring="Classes, Hooks">

```jsx

import { render, Component, createRef } from 'preact';

class LimitedInput extends Component {
	state = { value: '' };
	inputRef = createRef(null);

	onInput = e => {
		if (e.currentTarget.value.length <= 3) {
			this.setState({ value: e.currentTarget.value });
		} else {
			const start = this.inputRef.current.selectionStart;
			const end = this.inputRef.current.selectionEnd;
			const diffLength = Math.abs(
				e.currentTarget.value.length - this.state.value.length
			);
			this.inputRef.current.value = this.state.value;
			// Restore selection
			this.inputRef.current.setSelectionRange(
				start - diffLength,
				end - diffLength
			);
		}
	};

	render(_, { value }) {
		return (
			<div class="form-example">
				<label>
					This input is limited to 3 characters:{' '}
					<input ref={this.inputRef} value={value} onInput={this.onInput} />
				</label>
			</div>
		);
	}
}

render(<LimitedInput />, document.getElementById('app'));
```

```jsx

import { render } from 'preact';
import { useState, useRef } from 'preact/hooks';

const LimitedInput = () => {
	const [value, setValue] = useState('');
	const inputRef = useRef();

	const onInput = e => {
		if (e.currentTarget.value.length <= 3) {
			setValue(e.currentTarget.value);
		} else {
			const start = inputRef.current.selectionStart;
			const end = inputRef.current.selectionEnd;
			const diffLength = Math.abs(e.currentTarget.value.length - value.length);
			inputRef.current.value = value;
			// Restore selection
			inputRef.current.setSelectionRange(start - diffLength, end - diffLength);
		}
	};

	return (
		<div class="form-example">
			<label>
				This input is limited to 3 characters:{' '}
				<input ref={inputRef} value={value} onInput={onInput} />
			</label>
		</div>
	);
};

render(<LimitedInput />, document.getElementById('app'));
```

</tab-group>

------

**Description:** Refs are a way of creating stable values that are local to a component instance and persist across renders

### References

References, or refs for short, are stable, local values that persist across component renders but don't trigger rerenders like state or props would when they change.

Most often you'll see refs used to facilitate imperative manipulation of the DOM but they can be used to store any arbitrary local value that you need to be kept stable. You may use them to track a previous state value, keep a reference to an interval or timeout ID, or simply a counter value. Importantly, refs should not be used for rendering logic, instead, consumed in lifecycle methods and event handlers only.



#### Creating a Ref

There are two ways to create refs in Preact, depending on your preferred component style: `createRef` (class components) and `useRef` (function components/hooks). Both APIs fundamentally work the same way: they create a stable, plain object with a `current` property, optionally initialized to a value.

<tab-group tabstring="Classes, Hooks">

```jsx
import { createRef } from 'preact';

class MyComponent extends Component {
	countRef = createRef();
	inputRef = createRef(null);

	// ...
}
```

```jsx
import { useRef } from 'preact/hooks';

function MyComponent() {
	const countRef = useRef();
	const inputRef = useRef(null);

	// ...
}
```

</tab-group>

#### Using Refs to Access DOM Nodes

The most common use case for refs is to access the underlying DOM node of a component. This is useful for imperative DOM manipulation, such as measuring elements, calling native methods on various elements (such as `.focus()` or `.play()`), and integrating with third-party libraries written in vanilla JS. In the following examples, upon rendering, Preact will assign the DOM node to the `current` property of the ref object, making it available for use after the component has mounted.

<tab-group tabstring="Classes, Hooks">

```jsx

import { render, Component, createRef } from 'preact';

class MyInput extends Component {
	ref = createRef(null);

	componentDidMount() {
		console.log(this.ref.current);
		// Logs: [HTMLInputElement]
	}

	render() {
		return <input ref={this.ref} />;
	}
}

render(<MyInput />, document.getElementById('app'));
```

```jsx

import { render } from 'preact';
import { useRef, useEffect } from 'preact/hooks';

function MyInput() {
	const ref = useRef(null);

	useEffect(() => {
		console.log(ref.current);
		// Logs: [HTMLInputElement]
	}, []);

	return <input ref={ref} />;
}

render(<MyInput />, document.getElementById('app'));
```

</tab-group>

##### Callback Refs

Another way to use references is by passing a function to the `ref` prop, where the DOM node will be passed as an argument.

<tab-group tabstring="Classes, Hooks">

```jsx

import { render, Component } from 'preact';

class MyInput extends Component {
	render() {
		return (
			<input
				ref={dom => {
					console.log('Mounted:', dom);

					// As of Preact 10.23.0, you can optionally return a cleanup function
					return () => {
						console.log('Unmounted:', dom);
					};
				}}
			/>
		);
	}
}

render(<MyInput />, document.getElementById('app'));
```

```jsx

import { render } from 'preact';

function MyInput() {
	return (
		<input
			ref={dom => {
				console.log('Mounted:', dom);

				// As of Preact 10.23.0, you can optionally return a cleanup function
				return () => {
					console.log('Unmounted:', dom);
				};
			}}
		/>
	);
}

render(<MyInput />, document.getElementById('app'));
```

</tab-group>

> If the provided ref callback is unstable (such as one that's defined inline, as shown above), and _does not_ return a cleanup function, **it will be called twice** upon all rerenders: once with `null` and then once with the actual reference. This is a common issue and the `createRef`/`useRef` APIs make this a little easier by forcing the user to check if `ref.current` is defined.
>
> A stable function, for comparison, could be a method on the class component instance, a function defined outside of the component, or a function created with `useCallback`, for example.

#### Using Refs to Store Local Values

Refs aren't limited to storing DOM nodes, however; they can be used to store any type of value that you may need.

In the following example, we store the ID of an interval in a ref to be able to start & stop it independently.

<tab-group tabstring="Classes, Hooks">

```jsx

import { render, Component, createRef } from 'preact';

class SimpleClock extends Component {
	state = {
		time: Date.now()
	};
	intervalId = createRef(null);

	startClock = () => {
		this.setState({ time: Date.now() });
		this.intervalId.current = setInterval(() => {
			this.setState({ time: Date.now() });
		}, 1000);
	};

	stopClock = () => {
		clearInterval(this.intervalId.current);
	};

	render(_, { time }) {
		const formattedTime = new Date(time).toLocaleTimeString();

		return (
			<div>
				<button onClick={this.startClock}>Start Clock</button>
				<time dateTime={formattedTime}>{formattedTime}</time>
				<button onClick={this.stopClock}>Stop Clock</button>
			</div>
		);
	}
}

render(<SimpleClock />, document.getElementById('app'));
```

```jsx

import { render } from 'preact';
import { useState, useRef } from 'preact/hooks';

function SimpleClock() {
	const [time, setTime] = useState(Date.now());
	const intervalId = useRef(null);

	const startClock = () => {
		setTime(Date.now());
		intervalId.current = setInterval(() => {
			setTime(Date.now());
		}, 1000);
	};

	const stopClock = () => {
		clearInterval(intervalId.current);
	};

	const formattedTime = new Date(time).toLocaleTimeString();

	return (
		<div>
			<button onClick={startClock}>Start Clock</button>
			<time dateTime={formattedTime}>{formattedTime}</time>
			<button onClick={stopClock}>Stop Clock</button>
		</div>
	);
}

render(<SimpleClock />, document.getElementById('app'));
```

</tab-group>

------

**Description:** Context allows you to pass props through intermediate components. This documents describes both the new and the old API

### Context

Context is a way to pass data through the component tree without having to pass it through every component in-between via props. In a nutshell, it allows components anywhere in the hierarchy to subscribe to a value and get notified when it changes, bringing pub-sub-style updates to Preact.

It's not uncommon to run into situations in which a value from a grandparent component (or higher) needs to be passed down to a child, often without the intermediate component needing it. This process of passing down props is often referred to as "prop drilling" and can be cumbersome, error-prone, and just plain repetitive, especially as the application grows and more values have to be passed through more layers. This is one of the key issues Context aims to address by providing a way for a child to subscribe to a value higher up in the component tree, accessing the value without it being passed down as a prop.

There are two ways to use context in Preact: via the newer `createContext` API and the legacy context API. These days there's very few reasons to ever reach for the legacy API but it's documented here for completeness.



#### Modern Context API

##### Creating a Context

To create a new context, we use the `createContext` function. This function takes an initial state as an argument and returns an object with two component properties: `Provider`, to make the context available to descendants, and `Consumer`, to access the context value (primarily in class components).

```jsx
import { createContext } from 'preact';

export const Theme = createContext('light');
export const User = createContext({ name: 'Guest' });
export const Locale = createContext(null);
```

##### Setting up a Provider

Once we've created a context, we must make it available to descendants using the `Provider` component. The `Provider` must be given a `value` prop, representing the initial value of the context.

> The initial value set from `createContext` is only used in the absence of a `Provider` above the consumer in the tree. This may be helpful for testing components in isolation, as it avoids the need for creating a wrapping `Provider` around your component.

```jsx
import { createContext } from 'preact';

export const Theme = createContext('light');

function App() {
	return (
		<Theme.Provider value="dark">
			<SomeComponent />
		</Theme.Provider>
	);
}
```

> **Tip:** You can have multiple providers of the same context throughout your app but only the closest one to the consumer will be used.

##### Using the Context

There are three ways to consume a context, largely dependent on your preferred component style: `static contextType` (class components), the `useContext` hook (function components/hooks), and `Context.Consumer` (all components), .

<tab-group tabstring="contextType, useContext, Context.Consumer">

```jsx

import { render, createContext, Component } from 'preact';

const SomeComponent = props => props.children;

const ThemePrimary = createContext('#673ab8');

class ThemedButton extends Component {
	static contextType = ThemePrimary;

	render() {
		const theme = this.context;
		return <button style={{ background: theme }}>Themed Button</button>;
	}
}

function App() {
	return (
		<ThemePrimary.Provider value="#8f61e1">
			<SomeComponent>
				<ThemedButton />
			</SomeComponent>
		</ThemePrimary.Provider>
	);
}

render(<App />, document.getElementById('app'));
```

```jsx

import { render, createContext } from 'preact';
import { useContext } from 'preact/hooks';

const SomeComponent = props => props.children;

const ThemePrimary = createContext('#673ab8');

function ThemedButton() {
	const theme = useContext(ThemePrimary);
	return <button style={{ background: theme }}>Themed Button</button>;
}

function App() {
	return (
		<ThemePrimary.Provider value="#8f61e1">
			<SomeComponent>
				<ThemedButton />
			</SomeComponent>
		</ThemePrimary.Provider>
	);
}

render(<App />, document.getElementById('app'));
```

```jsx

import { render, createContext } from 'preact';

const SomeComponent = props => props.children;

const ThemePrimary = createContext('#673ab8');

function ThemedButton() {
	return (
		<ThemePrimary.Consumer>
			{theme => <button style={{ background: theme }}>Themed Button</button>}
		</ThemePrimary.Consumer>
	);
}

function App() {
	return (
		<ThemePrimary.Provider value="#8f61e1">
			<SomeComponent>
				<ThemedButton />
			</SomeComponent>
		</ThemePrimary.Provider>
	);
}

render(<App />, document.getElementById('app'));
```

</tab-group>

##### Updating the Context

Static values can be useful, but more often than not, we want to be able to update the context value dynamically. To do so, we leverage standard component state mechanisms:

```jsx

import { render, createContext } from 'preact';
import { useContext, useState } from 'preact/hooks';

const SomeComponent = props => props.children;

const ThemePrimary = createContext(null);

function ThemedButton() {
	const { theme } = useContext(ThemePrimary);
	return <button style={{ background: theme }}>Themed Button</button>;
}

function ThemePicker() {
	const { theme, setTheme } = useContext(ThemePrimary);
	return (
		<input
			type="color"
			value={theme}
			onChange={e => setTheme(e.currentTarget.value)}
		/>
	);
}

function App() {
	const [theme, setTheme] = useState('#673ab8');
	return (
		<ThemePrimary.Provider value={{ theme, setTheme }}>
			<SomeComponent>
				<ThemedButton />
				{' - '}
				<ThemePicker />
			</SomeComponent>
		</ThemePrimary.Provider>
	);
}

render(<App />, document.getElementById('app'));
```

#### Legacy Context API

This API is considered legacy and should be avoided in new code, it has known issues and only exists for backwards-compatibility reasons.

One of the key differences between this API and the new one is that this API cannot update a child when a component in-between the child and the provider aborts rendering via `shouldComponentUpdate`. When this happens, the child **will not** received the updated context value, often resulting in tearing (part of the UI using the new value, part using the old).

To pass down a value through the context, a component needs to have the `getChildContext` method, returning the intended context value. Descendants can then access the context via the second argument in function components or `this.context` in class-based components.

```jsx

import { render } from 'preact';

const SomeOtherComponent = props => props.children;

function ThemedButton(_props, context) {
	return <button style={{ background: context.theme }}>Themed Button</button>;
}

class App extends Component {
	getChildContext() {
		return {
			theme: '#673ab8'
		};
	}

	render() {
		return (
			<div>
				<SomeOtherComponent>
					<ThemedButton />
				</SomeOtherComponent>
			</div>
		);
	}
}

render(<App />, document.getElementById('app'));
```

------

## Debug & Test

**Description:** How to debug Preact applications when something goes wrong

### Debugging Preact Apps

Preact ships with a lot of tools to make debugging easier. They're packaged in a single import and can be included by importing `preact/debug`.

These include integration with our own [Preact Devtools] Extension for Chrome and Firefox.

We'll print a warning or an error whenever we detect something wrong like incorrect nesting in `<table>` elements.



#### Installation

The [Preact Devtools] can be installed in the extension store of your browser.

- [For Chrome](https://chrome.google.com/webstore/detail/preact-developer-tools/ilcajpmogmhpliinlbcdebhbcanbghmd)
- [For Firefox](https://addons.mozilla.org/en-US/firefox/addon/preact-devtools/)
- [For Edge](https://microsoftedge.microsoft.com/addons/detail/hdkhobcafnfejjieimdkmjaiihkjpmhk)

Once installed we need to import `preact/debug` somewhere to initialize the connection to the extension. Make sure that this import is **the first** import in your whole app.

> `@preact/preset-vite` includes the `preact/debug` package automatically. You can safely skip the setup & strip steps if you're using it!

Here is an example of how your main entry file to your application may look like.

```jsx
// Must be the first import
import 'preact/debug';
import { render } from 'preact';
import App from './components/App';

render(<App />, document.getElementById('root'));
```

##### Strip devtools from production

Most bundlers allow you strip out code when they detect that a branch inside an `if`-statement will never be hit. We can use this to only include `preact/debug` during development and save those precious bytes in a production build.

```jsx
// Must be the first import
if (process.env.NODE_ENV === 'development') {
	// Must use require here as import statements are only allowed
	// to exist at top-level.
	require('preact/debug');
}

import { render } from 'preact';
import App from './components/App';

render(<App />, document.getElementById('root'));
```

Make sure to set the `NODE_ENV` variable to the correct value in your build tool.

#### Debug Warnings and Errors

Sometimes you may get warnings or errors when Preact detects invalid code. These should be fixed to ensure that your app works flawlessly.

##### `undefined` parent passed to `render()`

This means that the code is trying to render your app into nothing instead of a DOM node. It's the difference between:

```jsx
// What Preact received
render(<App />, undefined);

// vs what it expected
render(<App />, actualDomNode);
```

The main reason this error occurs is that the DOM node isn't present when the `render()` function is called. Make sure it exists.

##### `undefined` component passed to `createElement()`

Preact will throw this error whenever you pass `undefined` instead of a component. The common cause for this one is mixing up `default` and `named` exports.

```jsx
// app.js
export default function App() {
	return <div>Hello World</div>;
}

// index.js: Wrong, because `app.js` doesn't have a named export
import { App } from './app';
render(<App />, dom);
```

The same error will be thrown when it's the other way around. When you declare a `named` export and are trying to use it as a `default` export. One quick way to check this (in case your editor won't do it already), is to just log out the import:

```jsx
// app.js
export function App() {
	return <div>Hello World</div>;
}

// index.js
import App from './app';

console.log(App);
// Logs: { default: [Function] } instead of the component
```

##### Passed a JSX literal as JSX twice

Passing a JSX-Literal or Component into JSX again is invalid and will trigger this error.

```jsx
const Foo = <div>foo</div>;
// Invalid: Foo already contains a JSX-Element
render(<Foo />, dom);
```

To fix this, we can just pass the variable directly:

```jsx
const Foo = <div>foo</div>;
render(Foo, dom);
```

##### Improper nesting of table detected

HTML parsers have very strict rules on how tables should be structured, deviating from which will lead to rendering errors that can be hard to debug. To help with this, Preact can detect improper nesting in a number of situations and will print warnings to catch this early. To learn more about how tables should be structured we can highly recommend [the MDN documentation](https://developer.mozilla.org/en-US/docs/Learn/HTML/Tables/Basics).

> **Note:** In this context, "strict" is referring to the _output_ of the HTML parser, not the _input_. Browsers are quite forgiving and try to correct invalid HTML where they can to ensure that pages can still be displayed. However, for VDOM libraries like Preact this can lead to issues as the input content might not match the output once the browser has corrected it which Preact will not be made aware of.
>
> For example, `<tr>` elements must always be a child of `<tbody>`, `<thead>`, or `<tfoot>` elements per the spec, but if you were to write a `<tr>` directly inside of a `<table>`, the browser will attempt to correct this by wrapping it in a `<tbody>` element for you. Preact will therefore expect the DOM structure to be `<table><tr></tr></table>` but the real DOM constructed by the browser would be `<table><tbody><tr></tr></tbody></table>`.

##### Invalid `ref`-property

When the `ref` property contains something unexpected we'll throw this error. This includes string-based `refs` that have been deprecated a while ago.

```jsx
// valid
<div ref={e => {/* ... */)}} />

// valid
const ref = createRef();
<div ref={ref} />

// Invalid
<div ref="ref" />
```

##### Invalid event handler

Sometimes you'll may accidentally pass a wrong value to an event handler. They must always be a `function` or `null` if you want to remove it. All other types are invalid.

```jsx
// valid
<div onClick={() => console.log("click")} />

// invalid
<div onClick={console.log("click")} />
```

##### Hook can only be invoked from render methods

This error occurs when you try to use a hook outside of a component. They are only supported inside a function component.

```jsx
// Invalid, must be used inside a component
const [value, setValue] = useState(0);

// valid
function Foo() {
	const [value, setValue] = useState(0);
	return <button onClick={() => setValue(value + 1)}>{value}</button>;
}
```

##### Getting `vnode.[property]` is deprecated

With Preact X we did some breaking changes to our internal `vnode` shape.

| Preact 8.x         | Preact 10.x            |
| ------------------ | ---------------------- |
| `vnode.nodeName`   | `vnode.type`           |
| `vnode.attributes` | `vnode.props`          |
| `vnode.children`   | `vnode.props.children` |

##### Found children with the same key

One unique aspect about virtual-dom based libraries is that they have to detect when a children is moved around. However to know which child is which, we need to flag them somehow. _This is only necessary when you're creating children dynamically._

```jsx
// Both children will have the same key "A"
<div>
	{['A', 'A'].map(char => (
		<p key={char}>{char}</p>
	))}
</div>
```

The correct way to do it is to give them unique keys. In most cases the data you're iterating over will have some form of `id`.

```jsx
const persons = [
	{ name: 'John', age: 22 },
	{ name: 'Sarah', age: 24 }
];

// Somewhere later in your component
<div>
	{persons.map(({ name, age }) => {
		return (
			<p key={name}>
				{name}, Age: {age}
			</p>
		);
	})}
</div>;
```

[preact devtools]: https://preactjs.github.io/preact-devtools/

------

**Description:** Testing Preact applications made easy with testing-library

### Testing with Preact Testing Library

The [Preact Testing Library](https://github.com/testing-library/preact-testing-library) is a lightweight wrapper around `preact/test-utils`. It provides a set of query methods for accessing the rendered DOM in a way similar to how a user finds elements on a page. This approach allows you to write tests that do not rely on implementation details. Consequently, this makes tests easier to maintain and more resilient when the component being tested is refactored.

Unlike [Enzyme](/guide/v10/unit-testing-with-enzyme), Preact Testing Library must be called inside a DOM environment.



#### Installation

Install the testing-library Preact adapter via the following command:

```bash
npm install --save-dev @testing-library/preact
```

> Note: This library relies on a DOM environment being present. If you're using [Jest](https://github.com/facebook/jest) it's already included and enabled by default. If you're using another test runner like [Mocha](https://github.com/mochajs/mocha) or [Jasmine](https://github.com/jasmine/jasmine) you can add a DOM environment to node by installing [jsdom](https://github.com/jsdom/jsdom).

#### Usage

Suppose we have a `Counter` component which displays an initial value, with a button to update it:

```jsx
import { h } from 'preact';
import { useState } from 'preact/hooks';

export function Counter({ initialCount }) {
	const [count, setCount] = useState(initialCount);
	const increment = () => setCount(count + 1);

	return (
		<div>
			Current value: {count}
			<button onClick={increment}>Increment</button>
		</div>
	);
}
```

We want to verify that our Counter displays the initial count and that clicking the button will increment it. Using the test runner of your choice, like [Jest](https://github.com/facebook/jest) or [Mocha](https://github.com/mochajs/mocha), we can write these two scenarios down:

```jsx
import { expect } from 'expect';
import { h } from 'preact';
import { render, fireEvent, screen, waitFor } from '@testing-library/preact';

import Counter from '../src/Counter';

describe('Counter', () => {
	test('should display initial count', () => {
		const { container } = render(<Counter initialCount={5} />);
		expect(container.textContent).toMatch('Current value: 5');
	});

	test('should increment after "Increment" button is clicked', async () => {
		render(<Counter initialCount={5} />);

		fireEvent.click(screen.getByText('Increment'));
		await waitFor(() => {
			// .toBeInTheDocument() is an assertion that comes from jest-dom.
			// Otherwise you could use .toBeDefined().
			expect(screen.getByText('Current value: 6')).toBeInTheDocument();
		});
	});
});
```

You may have noticed the `waitFor()` call there. We need this to ensure that Preact had enough time to render to the DOM and flush all pending effects.

```jsx
test('should increment counter", async () => {
  render(<Counter initialCount={5}/>);

  fireEvent.click(screen.getByText('Increment'));
  // WRONG: Preact likely won't have finished rendering here
  expect(screen.getByText("Current value: 6")).toBeInTheDocument();
});
```

Under the hood, `waitFor` repeatedly calls the passed callback function until it doesn't throw an error anymore or a timeout runs out (default: 1000ms). In the above example we know that the update is completed, when the counter is incremented and the new value is rendered into the DOM.

We can also write tests in an async-first way by using the "findBy" version of the queries instead of "getBy". Async queries retry using `waitFor` under the hood, and return Promises, so you need to await them.

```jsx
test('should increment counter", async () => {
  render(<Counter initialCount={5}/>);

  fireEvent.click(screen.getByText('Increment'));

  await screen.findByText('Current value: 6'); // waits for changed element

  expect(screen.getByText("Current value: 6")).toBeInTheDocument(); // passes
});
```

#### Finding Elements

With a full DOM environment in place, we can verify our DOM nodes directly. Commonly tests check for attributes being present like an input value or that an element appeared/disappeared. To do this, we need to be able to locate elements in the DOM.

##### Using Content

The Testing Library philosophy is that "the more your tests resemble the way your software is used, the more confidence they can give you".

The recommended way to interact with a page is by finding elements the way a user does, through the text content.

You can find a guide to picking the right query on the ['Which query should I use'](https://testing-library.com/docs/guide-which-query) page of the Testing Library docs. The simplest query is `getByText`, which looks at elements' `textContent`. There are also queries for label text, placeholder, title attributes, etc. The `getByRole` query is the most powerful in that it abstracts over the DOM and allows you to find elements in the accessibility tree, which is how your page is read by a screen reader. Combining [`role`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques) and [`accessible name`](https://www.w3.org/TR/accname-1.1/#mapping_additional_nd_name) covers many common DOM traversals in a single query.

```jsx
import { render, fireEvent, screen } from '@testing-library/preact';

test('should be able to sign in', async () => {
	render(<MyLoginForm />);

	// Locate the input using textbox role and the accessible name,
	// which is stable no matter if you use a label element, aria-label, or
	// aria-labelledby relationship
	const field = await screen.findByRole('textbox', { name: 'Sign In' });

	// type in the field
	fireEvent.change(field, { value: 'user123' });
});
```

Sometimes using text content directly creates friction when the content changes a lot, or if you use an internationalization framework that translates text into different languages. You can work around this by treating text as data that you snapshot, making it easy to update but keeping the source of truth outside the test.

```jsx
test('should be able to sign in', async () => {
	render(<MyLoginForm />);

	// What if we render the app in another language, or change the text? Test fails.
	const field = await screen.findByRole('textbox', { name: 'Sign In' });
	fireEvent.change(field, { value: 'user123' });
});
```

Even if you don't use a translation framework, you can keep your strings in a separate file and use the same strategy as in the example below:

```jsx
test('should be able to sign in', async () => {
	render(<MyLoginForm />);

	// We can use our translation function directly in the test
	const label = translate('signinpage.label', 'en-US');
	// Snapshot the result so we know what's going on
	expect(label).toMatchInlineSnapshot(`Sign In`);

	const field = await screen.findByRole('textbox', { name: label });
	fireEvent.change(field, { value: 'user123' });
});
```

##### Using Test IDs

Test IDs are data attributes added to DOM elements to help in cases where selecting content is ambiguous or unpredictable, or to decouple from implementation
details like DOM structure. They can be used when none of the other methods of finding elements make sense.

```jsx
function Foo({ onClick }) {
	return (
		<button onClick={onClick} data-testid="foo">
			click here
		</button>
	);
}

// Only works if the text stays the same
fireEvent.click(screen.getByText('click here'));

// Works if we change the text
fireEvent.click(screen.getByTestId('foo'));
```

#### Debugging Tests

To debug the current DOM state you can use the `debug()` function to print out a prettified version of the DOM.

```jsx
const { debug } = render(<App />);

// Prints out a prettified version of the DOM
debug();
```

#### Supplying custom Context Providers

Quite often you'll end up with a component which depends on shared context state. Common Providers typically range from Routers, State, to sometimes Themes and other ones that are global for your specific app. This can become tedious to set up for each test case repeatedly, so we recommend creating a custom `render` function by wrapping the one from `@testing-library/preact`.

```jsx
// helpers.js
import { render as originalRender } from '@testing-library/preact';
import { createMemoryHistory } from 'history';
import { FooContext } from './foo';

const history = createMemoryHistory();

export function render(vnode) {
	return originalRender(
		<FooContext.Provider value="foo">
			<Router history={history}>{vnode}</Router>
		</FooContext.Provider>
	);
}

// Usage like usual. Look ma, no providers!
render(<MyComponent />);
```

#### Testing Preact Hooks

With `@testing-library/preact` we can also test the implementation of our hooks!
Imagine that we want to re-use the counter functionality for multiple components (I know we love counters!) and have extracted it to a hook. And we now want to test it.

```jsx
import { useState, useCallback } from 'preact/hooks';

const useCounter = () => {
	const [count, setCount] = useState(0);
	const increment = useCallback(() => setCount(c => c + 1), []);
	return { count, increment };
};
```

Like before, the approach behind it is similar: We want to verify that we can increment our counter. So we need to somehow call our hook. This can be done with the `renderHook()`-function, which automatically creates a surrounding component internally. The function returns the current hook return value under `result.current`, which we can use to do our verifications:

```jsx
import { renderHook, act } from '@testing-library/preact';
import useCounter from './useCounter';

test('should increment counter', () => {
	const { result } = renderHook(() => useCounter());

	// Initially the counter should be 0
	expect(result.current.count).toBe(0);

	// Let's update the counter by calling a hook callback
	act(() => {
		result.current.increment();
	});

	// Check that the hook return value reflects the new state.
	expect(result.current.count).toBe(1);
});
```

For more information about `@testing-library/preact` check out https://github.com/testing-library/preact-testing-library .

------

**Description:** Testing Preact applications made easy with enzyme

### Unit Testing with Enzyme

Airbnb's [Enzyme](https://airbnb.io/enzyme/) is a library for writing
tests for React components. It supports different versions of React and
React-like libraries using "adapters". There is an adapter for Preact,
maintained by the Preact team.

Enzyme supports tests that run in a normal or headless browser using a tool
such as [Karma](http://karma-runner.github.io/latest/index.html) or tests that
run in Node using [jsdom](https://github.com/jsdom/jsdom) as a fake
implementation of browser APIs.

For a detailed introduction to using Enzyme and an API reference, see the
[Enzyme documentation](https://airbnb.io/enzyme/). The remainder of this guide
explains how to set Enzyme up with Preact, as well as ways in which Enzyme with
Preact differs from Enzyme with React.



#### Installation

Install Enzyme and the Preact adapter using:

```bash
npm install --save-dev enzyme enzyme-adapter-preact-pure
```

#### Configuration

In your test setup code, you'll need to configure Enzyme to use the Preact
adapter:

```js
import { configure } from 'enzyme';
import Adapter from 'enzyme-adapter-preact-pure';

configure({ adapter: new Adapter() });
```

For guidance on using Enzyme with different test runners, see the
[Guides](https://airbnb.io/enzyme/docs/guides.html) section of the Enzyme
documentation.

#### Example

Suppose we have a simple `Counter` component which displays an initial value,
with a button to update it:

```jsx
import { h } from 'preact';
import { useState } from 'preact/hooks';

export default function Counter({ initialCount }) {
	const [count, setCount] = useState(initialCount);
	const increment = () => setCount(count + 1);

	return (
		<div>
			Current value: {count}
			<button onClick={increment}>Increment</button>
		</div>
	);
}
```

Using a test runner such as mocha or Jest, you can write a test to check that
it works as expected:

```jsx
import { expect } from 'chai';
import { h } from 'preact';
import { mount } from 'enzyme';

import Counter from '../src/Counter';

describe('Counter', () => {
	it('should display initial count', () => {
		const wrapper = mount(<Counter initialCount={5} />);
		expect(wrapper.text()).to.include('Current value: 5');
	});

	it('should increment after "Increment" button is clicked', () => {
		const wrapper = mount(<Counter initialCount={5} />);

		wrapper.find('button').simulate('click');

		expect(wrapper.text()).to.include('Current value: 6');
	});
});
```

For a runnable version of this project and other examples, see the
[examples/](https://github.com/preactjs/enzyme-adapter-preact-pure/blob/master/README.md#example-projects)
directory in the Preact adapter's repository.

#### How Enzyme works

Enzyme uses the adapter library it has been configured with to render a
component and its children. The adapter then converts the output to a
standardized internal representation (a "React Standard Tree"). Enzyme then wraps
this with an object that has methods to query the output and trigger updates.
The wrapper object's API uses CSS-like
[selectors](https://airbnb.io/enzyme/docs/api/selector.html) to locate parts of
the output.

#### Full, shallow and string rendering

Enzyme has three rendering "modes":

```jsx
import { mount, shallow, render } from 'enzyme';

// Render the full component tree:
const wrapper = mount(<MyComponent prop="value" />);

// Render only `MyComponent`'s direct output (ie. "mock" child components
// to render only as placeholders):
const wrapper = shallow(<MyComponent prop="value" />);

// Render the full component tree to an HTML string, and parse the result:
const wrapper = render(<MyComponent prop="value" />);
```

- The `mount` function renders the component and all of its descendants in the
  same way they would be rendered in the browser.

- The `shallow` function renders only the DOM nodes that are directly output
  by the component. Any child components are replaced with placeholders that
  output just their children.

  The advantage of this mode is that you can write tests for components without
  depending on the details of child components and needing to construct all
  of their dependencies.

  The `shallow` rendering mode works differently internally with the Preact
  adapter compared to React. See the Differences section below for details.

- The `render` function (not to be confused with Preact's `render` function!)
  renders a component to an HTML string. This is useful for testing the output
  of rendering on the server, or rendering a component without triggering any
  of its effects.

#### Triggering state updates and effects with `act`

In the previous example, `.simulate('click')` was used to click on a button.

Enzyme knows that calls to `simulate` are likely to change the state of a
component or trigger effects, so it will apply any state updates or effects
immediately before `simulate` returns. Enzyme does the same when the component
is rendered initially using `mount` or `shallow` and when a component is updated
using `setProps`.

If however an event happens outside of an Enzyme method call, such as directly
calling an event handler (eg. the button's `onClick` prop), then Enzyme will not
be aware of the change. In this case, your test will need to trigger execution
of state updates and effects and then ask Enzyme to refresh its view of the
output.

- To execute state updates and effects synchronously, use the `act` function
  from `preact/test-utils` to wrap the code that triggers the updates
- To update Enzyme's view of rendered output use the wrapper's `.update()`
  method

For example, here is a different version of the test for incrementing the
counter, modified to call the button's `onClick` prop directly, instead of going
through the `simulate` method:

```js
import { act } from 'preact/test-utils';
```

```jsx
it('should increment after "Increment" button is clicked', () => {
	const wrapper = mount(<Counter initialCount={5} />);
	const onClick = wrapper.find('button').props().onClick;

	act(() => {
		// Invoke the button's click handler, but this time directly, instead of
		// via an Enzyme API
		onClick();
	});
	// Refresh Enzyme's view of the output
	wrapper.update();

	expect(wrapper.text()).to.include('Current value: 6');
});
```

#### Differences from Enzyme with React

The general intent is that tests written using Enzyme + React can be easily made
to work with Enzyme + Preact or vice-versa. This avoids the need to rewrite all
of your tests if you need to switch a component initially written for Preact
to work with React or vice-versa.

However there are some differences in behavior between this adapter and Enzyme's
React adapters to be aware of:

- The "shallow" rendering mode works differently under the hood. It is
  consistent with React in only rendering a component "one level deep" but,
  unlike React, it creates real DOM nodes. It also runs all of the normal
  lifecycle hooks and effects.
- The `simulate` method dispatches actual DOM events, whereas in the React
  adapters, `simulate` just calls the `on<EventName>` prop
- In Preact, state updates (eg. after a call to `setState`) are batched together
  and applied asynchronously. In React state updates can be applied immediately
  or batched depending on the context. To make writing tests easier, the
  Preact adapter flushes state updates and effects after initial renders and
  updates triggered via `setProps` or `simulate` calls on an adapter. When state updates or
  effects are triggered by other means, your test code may need to manually
  trigger flushing of effects and state updates using `act` from
  the `preact/test-utils` package.

For further details, see [the Preact adapter's
README](https://github.com/preactjs/enzyme-adapter-preact-pure#differences-compared-to-enzyme--react).

------

## React compatibility

**Description:** What are the differences between Preact and React. This document describes them in detail

### Differences to React

Preact is not intended to be a reimplementation of React. There are differences. Many of these differences are trivial, or can be completely removed by using [preact/compat], which is a thin layer over Preact that attempts to achieve 100% compatibility with React.

The reason Preact does not attempt to include every single feature of React is in order to remain **small** and **focused** - otherwise it would make more sense to simply submit optimizations to the React project, which is already a very complex and well-architected codebase.



#### Main differences

The main difference between Preact and React is that Preact does not implement a synthetic event system for size and performance reasons. Preact uses the browser's standard `addEventListener` to register event handlers, which means event naming and behavior works the same in Preact as it does in plain JavaScript / DOM. See [MDN's Event Reference] for a full list of DOM event handlers.

Standard browser events work very similarly to how events work in React, with a few small differences. In Preact:

- events don't bubble up through `<Portal>` components
- standard `onInput` should be used instead of React's `onChange` for form inputs (**only if `preact/compat` is not used**)
- standard `onDblClick` should be used instead of React's `onDoubleClick` (**only if `preact/compat` is not used**)
- `onSearch` should generally be used for `<input type="search">`, since the clear "x" button does not fire `onInput` in IE11

Another notable difference is that Preact follows the DOM specification more closely. Custom elements are supported like any other element, and custom events are supported with case-sensitive names (as they are in the DOM).

#### Version Compatibility

For both preact and [preact/compat], version compatibility is measured against the _current_ and _previous_ major releases of React. When new features are announced by the React team, they may be added to Preact's core if it makes sense given the [Project Goals]. This is a fairly democratic process, constantly evolving through discussion and decisions made in the open, using issues and pull requests.

> Thus, the website and documentation reflect React `15.x` through `17.x`, with some `18.x` and `19.x` additions, when discussing compatibility or making comparisons.

#### Debug messages and errors

Our flexible architecture allows addons to enhance the Preact experience in any way they want. One of those addons is `preact/debug` which adds [helpful warnings and errors](/guide/v10/debugging) and attaches the [Preact Developer Tools](https://preactjs.github.io/preact-devtools/) browser extension, if installed. Those guide you when developing Preact applications and make it a lot easier to inspect what's going on. You can enable them by adding the relevant import statement:

```js
import 'preact/debug'; // <-- Add this line at the top of your main entry file
```

This is different from React which requires a bundler being present that strips out debugging messages at build time by checking for `NODE_ENV != "production"`.

#### Features unique to Preact

Preact actually adds a few convenient features inspired by work in the (P)React community:

##### Native support for ES Modules

Preact was built with ES Modules in mind from the beginning, and was one of the first frameworks to support them. You can load Preact via the `import` keyword directly in browsers without having it to pass through a bundler first.

##### Arguments in `Component.render()`

For convenience, we pass `this.props` and `this.state` to the `render()` method on class components. Take a look at this component which uses one prop and one state property.

```jsx
// Works in both Preact and React
class Foo extends Component {
	state = { age: 1 };

	render() {
		return (
			<div>
				Name: {this.props.name}, Age: {this.state.age}
			</div>
		);
	}
}
```

In Preact this can be also written like this:

```jsx
// Only works in Preact
class Foo extends Component {
	state = { age: 1 };

	render({ name }, { age }) {
		return (
			<div>
				Name: {name}, Age: {age}
			</div>
		);
	}
}
```

Both snippets render the exact same thing, render arguments are provided for convenience.

##### Raw HTML attribute/property names

Preact aims to closely match the DOM specification supported by all major browsers. When applying `props` to an element, Preact _detects_ whether each prop should be set as a property or HTML attribute. This makes it possible to set complex properties on Custom Elements, but it also means you can use attribute names like `class` in JSX:

```jsx
// This:
<div class="foo" />

// ...is the same as:
<div className="foo" />
```

Most Preact developers prefer to use `class` instead of `className` as it's shorter to write but both are supported.

##### SVG inside JSX

SVG is pretty interesting when it comes to the names of its properties and attributes. Some properties (and their attributes) on SVG objects are camelCased (e.g. [clipPathUnits on a clipPath element](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/clipPath#Attributes)), some attributes are kebab-case (e.g. [clip-path on many SVG elements](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/Presentation)), and other attributes (usually ones inherited from the DOM, e.g. `oninput`) are all lowercase.

Preact applies SVG attributes as-written. This means you can copy and paste unmodified SVG snippets right into your code and have them work out of the box. This allows greater interoperability with tools designers tend to use to generate icons or SVG illustrations.

```jsx
// React
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48">
  <circle fill="none" strokeWidth="2" strokeLinejoin="round" cx="24" cy="24" r="20" />
</svg>
// Preact (note stroke-width and stroke-linejoin)
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48">
  <circle fill="none" stroke-width="2" stroke-linejoin="round" cx="24" cy="24" r="20" />
</svg>
```

If you're coming from React, you may be used to specifying all attributes in camelCase. You can continue to use always-camelCase SVG attribute names by adding [preact/compat] to your project, which mirrors the React API and normalizes these attributes.

##### Use `onInput` instead of `onChange`

Largely for historical reasons, the semantics of React's `onChange` event are actually the same as the `onInput` event provided by browsers, which is supported everywhere. The `input` event is the best-suited event for the majority of cases where you want to react when a form control is modified. In Preact core, `onChange` is the standard [DOM change event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event) that gets fired when an element's value is _committed_ by the user.

```jsx
// React
<input onChange={e => console.log(e.currentTarget.value)} />

// Preact
<input onInput={e => console.log(e.currentTarget.value)} />
```

If you're using [preact/compat], most `onChange` events are internally converted to `onInput` to emulate React's behavior. This is one of the tricks we use to ensure maximum compatibility with the React ecosystem.

##### JSX Constructor

JSX is a syntax extension for JavaScript that is converted to nested function calls. The idea of using these nested calls to build up tree structures long predates JSX, and was previously popularized in JavaScript by the [hyperscript] project. This approach has value well beyond the scope of the React ecosystem, so Preact promotes the original generalized community-standard. For a more in-depth discussion of JSX and its relationship to Hyperscript, [read this article on how JSX works](https://jasonformat.com/wtf-is-jsx).

**Source:** (JSX)

```jsx
<a href="/">
	<span>Home</span>
</a>
```

**Output:**

```js
// Preact:
h('a', { href: '/' }, h('span', null, 'Home'));

// React:
React.createElement(
	'a',
	{ href: '/' },
	React.createElement('span', null, 'Home')
);
```

Ultimately, if you're looking at the generated output code for a Preact application, it's clear that a shorter un-namespaced "JSX pragma" is both easier to read _and_ more suitable for optimizations like minification. In most Preact apps you'll encounter `h()`, though it doesn't really matter which name you use since a `createElement` alias export is also provided.

##### No contextTypes needed

The legacy `Context` API requires Components to declare specific properties using React's `contextTypes` or `childContextTypes` in order to receive those values. Preact does not have this requirement: all Components receive all `context` properties produced by `getChildContext()` by default.

#### Features exclusive to `preact/compat`

`preact/compat` is our **compat**ibility layer that translates React code to Preact. For existing React users this can be an easy way to try out Preact without changing any of your code, by [setting up a few aliases](/guide/v10/getting-started#aliasing-react-to-preact) in your bundler configuration.

##### Children API

The `Children` API is a specialized set of methods for working with the value of `props.children`. For Preact this is generally unnecessary, and we recommend using the built-in array methods instead. In Preact, `props.children` is either a Virtual DOM node, an empty value like `null`, or an Array of Virtual DOM nodes. The first two cases are the simplest and most common, since it's possible to use or return `children` as-is:

```jsx
// React:
function App(props) {
	return <Modal content={Children.only(props.children)} />;
}

// Preact: use props.children directly:
function App(props) {
	return <Modal content={props.children} />;
}
```

For specialized cases where you need to iterate over the children passed to a component, Preact provides a `toChildArray()` method that accepts any `props.children` value and returns a flattened and normalized Array of Virtual DOM nodes.

```jsx
// React
function App(props) {
	const cols = Children.count(props.children);
	return <div data-columns={cols}>{props.children}</div>;
}

// Preact
function App(props) {
	const cols = toChildArray(props.children).length;
	return <div data-columns={cols}>{props.children}</div>;
}
```

A React-compatible `Children` API is available from `preact/compat` to make integration with existing component libraries seamless.

##### Specialised Components

[preact/compat] ships with specialised components that are not necessary for every app. These include

- [PureComponent](/guide/v10/switching-to-preact#purecomponent): Only updates if `props` or `state` have changed
- [memo](/guide/v10/switching-to-preact#memo): Similar in spirit to `PureComponent` but allows to use a custom comparison function
- [forwardRef](/guide/v10/switching-to-preact#forwardref): Supply a `ref` to a specified child component.
- [Portals](/guide/v10/switching-to-preact#portals): Continues rendering the current tree into a different DOM container
- [Suspense](/guide/v10/switching-to-preact#suspense-experimental): **experimental** Allows to display fallback content in case the tree is not ready
- [lazy](/guide/v10/switching-to-preact#suspense-experimental): **experimental** Lazy load async code and mark a tree as ready/not ready accordingly.

[project goals]: /about/project-goals
[hyperscript]: https://github.com/dominictarr/hyperscript
[preact/compat]: /guide/v10/switching-to-preact
[mdn's event reference]: https://developer.mozilla.org/en-US/docs/Web/Events

------

**Description:** Everything you need to know to switch from React to Preact

### Switching to Preact (from React)

`preact/compat` is our compatibility layer that allows you to leverage the many libraries of the React ecosystem and use them with Preact. This is the recommended way to try out Preact if you have an existing React app.

This lets you continue writing React/ReactDOM code without any changes to your workflow or codebase. `preact/compat` adds somewhere around 2kb to your bundle size, but has the advantage of supporting the vast majority of existing React modules you might find on npm. The `preact/compat` package provides all the necessary tweaks on top of Preact's core to make it work just like `react` and `react-dom`, in a single module.



#### Setting up compat

To set up `preact/compat` you need to alias `react` and `react-dom` to `preact/compat`. The [Getting Started](/guide/v10/getting-started#aliasing-react-to-preact) page goes into detail on how aliasing is configured in various bundlers.

#### PureComponent

The `PureComponent` class works similar to `Component`. The difference is that `PureComponent` will skip rendering when the new props are equal to the old ones. To do this we compare the old and new props via a shallow comparison where we check each props property for referential equality. This can speed up applications a lot by avoiding unnecessary re-renders. It works by adding a default `shouldComponentUpdate` lifecycle hook.

```jsx
import { render } from 'preact';
import { PureComponent } from 'preact/compat';

class Foo extends PureComponent {
	render(props) {
		console.log('render');
		return <div />;
	}
}

const dom = document.getElementById('root');
render(<Foo value="3" />, dom);
// Logs: "render"

// Render a second time, doesn't log anything
render(<Foo value="3" />, dom);
```

> Note that the advantage of `PureComponent` only pays off when then render is expensive. For simple children trees it can be quicker to just do the `render` compared to the overhead of comparing props.

#### memo

`memo` is equivalent to functional components as `PureComponent` is to classes. It uses the same comparison function under the hood, but allows you to specify your own specialized function optimized for your use case.

```jsx
import { memo } from 'preact/compat';

function MyComponent(props) {
	return <div>Hello {props.name}</div>;
}

// Usage with default comparison function
const Memoed = memo(MyComponent);

// Usage with custom comparison function
const Memoed2 = memo(MyComponent, (prevProps, nextProps) => {
	// Only re-render when `name' changes
	return prevProps.name === nextProps.name;
});
```

> The comparison function is different from `shouldComponentUpdate` in that it checks if the two props objects are **equal**, whereas `shouldComponentUpdate` checks if they are different.

#### forwardRef

In some cases when writing a component you want to allow the user to get hold of a specific reference further down the tree. With `forwardRef` you can sort-of "forward" the `ref` property:

```jsx
import { createRef, render } from 'preact';
import { forwardRef } from 'preact/compat';

const MyComponent = forwardRef((props, ref) => {
	return <div ref={ref}>Hello world</div>;
});

// Usage: `ref` will hold the reference to the inner `div` instead of
// `MyComponent`
const ref = createRef();
render(<MyComponent ref={ref} />, dom);
```

This component is most useful for library authors.

#### Portals

In rare circumstances you may want to continue rendering into a different DOM node. The target DOM node **must** be present before attempting to render into it.

```html
<html>
	<body>
		<!-- App is rendered here -->
		<div id="app"></div>
		<!-- Modals should be rendered here -->
		<div id="modals"></div>
	</body>
</html>
```

```jsx
import { createPortal } from 'preact/compat';
import MyModal from './MyModal';

function App() {
	const container = document.getElementById('modals');
	return (
		<div>
			I'm app
			{createPortal(<MyModal />, container)}
		</div>
	);
}
```

> Keep in mind that due to Preact reusing the browser's event system, events won't bubble up through a Portal container to the other tree.

#### Suspense

The main idea behind `Suspense` is to allow sections of your UI to display some sort of placeholder content while components further down the tree are still loading. A common use case for this is code-splitting where you'll need to load a component from the network before you can render it.

```jsx
import { Suspense, lazy } from 'preact/compat';

const SomeComponent = lazy(() => import('./SomeComponent'));

// Usage
<Suspense fallback={<div>loading...</div>}>
	<Foo>
		<SomeComponent />
	</Foo>
</Suspense>;
```

In this example the UI will display the `loading...` text until `SomeComponent` is loaded and the Promise is resolved.

> Suspense in both React and Preact isn't quite finalized or set in stone as of yet. While the React team still actively discourages users interfacing with it directly for data fetching, it's a pattern some Preact users have been happily using over the last few years. There are a few known issues (please see [our tracker](https://github.com/preactjs/preact/issues?q=is%3Aissue+is%3Aopen+suspense) for an up-to-date reference) but it's generally considered stable enough for use in production if you so wish.
>
> This site, for instance, is built using a Suspense-based data fetching strategy used to load all content you see.

------

## Advanced

**Description:** Learn more about all exported functions of the Preact module

### API Reference

This page serves as a quick overview over all exported functions.



#### Component

`Component` is a base class that can be extended to create stateful Preact components.

Rather than being instantiated directly, Components are managed by the renderer and created as-needed.

```js
import { Component } from 'preact';

class MyComponent extends Component {
	// (see below)
}
```

##### Component.render(props, state)

All components must provide a `render()` function. The render function is passed the component's current props and state, and should return a Virtual DOM Element (typically a JSX "element"), an Array, or `null`.

```jsx
import { Component } from 'preact';

class MyComponent extends Component {
	render(props, state) {
		// props is the same as this.props
		// state is the same as this.state

		return <h1>Hello, {props.name}!</h1>;
	}
}
```

To learn more about components and how they can be used, check out the [Components Documentation](/guide/v10/components).

#### render()

`render(virtualDom, containerNode, [replaceNode])`

Render a Virtual DOM Element into a parent DOM element `containerNode`. Does not return anything.

```jsx

// DOM tree before render:
// <div id="container"></div>

import { render } from 'preact';

const Foo = () => <div>foo</div>;

render(<Foo />, document.getElementById('container'));

// After render:
// <div id="container">
//  <div>foo</div>
// </div>
```

If the optional `replaceNode` parameter is provided, it must be a child of `containerNode`. Instead of inferring where to start rendering, Preact will update or replace the passed element using its diffing algorithm.

> ⚠️ The `replaceNode`-argument will be removed with Preact `v11`. It introduces too many edge cases and bugs which need to be accounted for in the rest of Preact's source code. We're leaving this section up for historical reasons, but we don't recommend anyone to use the third `replaceNode` argument.

```jsx
// DOM tree before render:
// <div id="container">
//   <div>bar</div>
//   <div id="target">foo</div>
// </div>

import { render } from 'preact';

const Foo = () => <div id="target">BAR</div>;

render(
	<Foo />,
	document.getElementById('container'),
	document.getElementById('target')
);

// After render:
// <div id="container">
//   <div>bar</div>
//   <div id="target">BAR</div>
// </div>
```

The first argument must be a valid Virtual DOM Element, which represents either a component or an element. When passing a Component, it's important to let Preact do the instantiation rather than invoking your component directly, which will break in unexpected ways:

```jsx
const App = () => <div>foo</div>;

// DON'T: Invoking components directly means they won't be counted as a
// VNode and hence not be able to use functionality relating to vnodes.
render(App(), rootElement); // ERROR
render(App, rootElement); // ERROR

// DO: Passing components using h() or JSX allows Preact to render correctly:
render(h(App), rootElement); // success
render(<App />, rootElement); // success
```

#### hydrate()

If you've already pre-rendered or server-side-rendered your application to HTML, Preact can bypass most rendering work when loading in the browser. This can be enabled by switching from `render()` to `hydrate()`, which skips most diffing while still attaching event listeners and setting up your component tree. This works only when used in conjunction with pre-rendering or [Server-Side Rendering](/guide/v10/server-side-rendering).

```jsx

import { hydrate } from 'preact';

const Foo = () => <div>foo</div>;
hydrate(<Foo />, document.getElementById('container'));
```

#### h() / createElement()

`h(type, props, ...children)`

Returns a Virtual DOM Element with the given `props`. Virtual DOM Elements are lightweight descriptions of a node in your application's UI hierarchy, essentially an object of the form `{ type, props }`.

After `type` and `props`, any remaining parameters are collected into a `children` property.
Children may be any of the following:

- Scalar values (string, number, boolean, null, undefined, etc)
- Nested Virtual DOM Elements
- Infinitely nested Arrays of the above

```js
import { h } from 'preact';

h('div', { id: 'foo' }, 'Hello!');
// <div id="foo">Hello!</div>

h('div', { id: 'foo' }, 'Hello', null, ['Preact!']);
// <div id="foo">Hello Preact!</div>

h('div', { id: 'foo' }, h('span', null, 'Hello!'));
// <div id="foo"><span>Hello!</span></div>
```

#### toChildArray

This helper function converts a `props.children` value to a flattened Array regardless of its structure or nesting. If `props.children` is already an array, a copy is returned. This function is useful in cases where `props.children` may not be an array, which can happen with certain combinations of static and dynamic expressions in JSX.

For Virtual DOM Elements with a single child, `props.children` is a reference to the child. When there are multiple children, `props.children` is always an Array. The `toChildArray` helper provides a way to consistently handle all cases.

```jsx
import { toChildArray } from 'preact';

function Foo(props) {
	const count = toChildArray(props.children).length;
	return <div>I have {count} children</div>;
}

// props.children is "bar"
render(<Foo>bar</Foo>, container);

// props.children is [<p>A</p>, <p>B</p>]
render(
	<Foo>
		<p>A</p>
		<p>B</p>
	</Foo>,
	container
);
```

#### cloneElement

`cloneElement(virtualElement, props, ...children)`

This function allows you to create a shallow copy of a Virtual DOM Element.
It's generally used to add or overwrite `props` of an element:

```jsx
function Linkout(props) {
	// add target="_blank" to the link:
	return cloneElement(props.children, { target: '_blank' });
}
render(
	<Linkout>
		<a href="/">home</a>
	</Linkout>
);
// <a href="/" target="_blank">home</a>
```

#### createContext

See the section in the [Context documentation](/guide/v10/context#createcontext).

#### createRef

Provides a way to reference an element or component once it has been rendered.

See the [References documentation](/guide/v10/refs#createref) for more details.

#### Fragment

A special kind of component that can have children, but is not rendered as a DOM element.
Fragments make it possible to return multiple sibling children without needing to wrap them in a DOM container:

```jsx

import { Fragment, render } from 'preact';

render(
	<Fragment>
		<div>A</div>
		<div>B</div>
		<div>C</div>
	</Fragment>,
	document.getElementById('container')
);
// Renders:
// <div id="container>
//   <div>A</div>
//   <div>B</div>
//   <div>C</div>
// </div>
```

------

**Description:** How to use web components with Preact

### Web Components

Web Components are a set of different technologies that allow you to create reusable, encapsulated custom HTML elements that are entirely framework-agnostic. Examples of Web Components include elements like `<material-card>` or `<tab-bar>`.

As a platform primitive, Preact [fully supports Web Components](https://custom-elements-everywhere.com/#preact), allowing seamless use of Custom Element lifecycles, properties, and events in your Preact apps.

Preact and Web Components are complementary technologies: Web Components provide a set of low-level primitives for extending the browser, and Preact provides a high-level component model that can sit atop those primitives.



#### Rendering Web Components

In Preact, web components work just like other DOM Elements. They can be rendered using their registered tag name:

```jsx
customElements.define(
	'x-foo',
	class extends HTMLElement {
		// ...
	}
);

function Foo() {
	return <x-foo />;
}
```

##### Properties and Attributes

JSX does not provide a way to differentiate between properties and attributes. Custom Elements generally rely on custom properties in order to support setting complex values that can't be expressed as attributes. This works well in Preact, because the renderer automatically determines whether to set values using a property or attribute by inspecting the affected DOM element. When a Custom Element defines a [setter](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/set) for a given property, Preact detects its existence and will use the setter instead of an attribute.

```jsx
customElements.define(
	'context-menu',
	class extends HTMLElement {
		set position({ x, y }) {
			this.style.cssText = `left:${x}px; top:${y}px;`;
		}
	}
);

function Foo() {
	return <context-menu position={{ x: 10, y: 20 }}> ... </context-menu>;
}
```

> **Note:** Preact makes no assumptions over naming schemes and will not attempt to coerce names, in JSX or otherwise, to DOM properties. If a custom element has a property name `someProperty`, then it will need to be set using that exact same capitalization and spelling (`someProperty=...`). `someproperty=...` or `some-property=...` will not work.

When rendering static HTML using `preact-render-to-string` ("SSR"), complex property values like the object above are not automatically serialized. They are applied once the static HTML is hydrated on the client.

##### Accessing Instance Methods

To be able to access the instance of your custom web component, we can leverage `refs`:

```jsx
function Foo() {
	const myRef = useRef(null);

	useEffect(() => {
		if (myRef.current) {
			myRef.current.doSomething();
		}
	}, []);

	return <x-foo ref={myRef} />;
}
```

##### Triggering custom events

Preact normalizes the casing of standard built-in DOM Events, which are normally case-sensitive. This is the reason it's possible to pass an `onChange` prop to `<input>`, despite the actual event name being `"change"`. Custom Elements often fire custom events as part of their public API, however there is no way to know what custom events might be fired. In order to ensure Custom Elements are seamlessly supported in Preact, unrecognized event handler props passed to a DOM Element are registered using their casing exactly as specified.

```jsx
// Built-in DOM event: listens for a "click" event
<input onClick={() => console.log('click')} />

// Custom Element: listens for "TabChange" event (case-sensitive!)
<tab-bar onTabChange={() => console.log('tab change')} />

// Corrected: listens for "tabchange" event (lower-case)
<tab-bar ontabchange={() => console.log('tab change')} />
```

------

**Description:** Render your Preact application on the server to show content to users quicker

### Server-Side Rendering

Server-Side Rendering (often abbreviated as "SSR") allows you to render your application to an HTML string that can be sent to the client to improve load time. Outside of that there are other scenarios, like testing, where SSR proves really useful.



#### Installation

The server-side renderer for Preact lives in its [own repository](https://github.com/preactjs/preact-render-to-string/) and can be installed via your packager of choice:

```bash
npm install -S preact-render-to-string
```

After the command above finished, we can start using it right away.

#### HTML Strings

Both of the following options return a single HTML string that represents the full rendered output of your Preact application.

##### renderToString

The most basic and straightforward rendering method, `renderToString` transforms a Preact tree into a string of HTML synchronously.

```jsx
import { renderToString } from 'preact-render-to-string';

const name = 'Preact User!';
const App = <div class="foo">Hello {name}</div>;

const html = renderToString(App);
console.log(html);
// <div class="foo">Hello Preact User!</div>
```

##### renderToStringAsync

Awaits the resolution of promises before returning the complete HTML string. This is particularly useful when utilizing suspense for lazy-loaded components or data fetching.

```jsx
// app.js
import { Suspense, lazy } from 'preact/compat';

const HomePage = lazy(() => import('./pages/home.js'));

function App() {
	return (
		<Suspense fallback={<p>Loading</p>}>
			<HomePage />
		</Suspense>
	);
}
```

```jsx
import { renderToStringAsync } from 'preact-render-to-string';
import { App } from './app.js';

const html = await renderToStringAsync(<App />);
console.log(html);
// <h1>Home page</h1>
```

> **Note:** Unfortunately there's a handful of known limitations in Preact v10's implementation of "resumed hydration" — that is, hydration that can pause and wait for JS chunks or data to be downloaded & available before continuing. This has been solved in the upcoming Preact v11 release.
>
> For now, you'll want to avoid async boundaries that return 0 or more than 1 DOM node as children, such as in the following examples:
>
> ```jsx
> function X() {
>   // Some lazy operation, such as initializing analytics
>   return null;
> };
>
> const LazyOperation = lazy(() => /* import X */);
> ```
>
> ```jsx
> function Y() {
>   // `<Fragment>` disappears upon rendering, leaving two `<p>` DOM elements
>   return (
>     <Fragment>
>       <p>Foo</p>
>       <p>Bar</p>
>     </Fragment>
>   );
> };
>
> const SuspendingMultipleChildren = lazy(() => /* import Y */);
> ```
>
> For a more comprehensive write up of the known problems and how we have addressed them, please see [Hydration 2.0 (preactjs/preact#4442)](https://github.com/preactjs/preact/issues/4442)

#### HTML Streams

Streaming is a method of rendering that allows you to send parts of your Preact application to the client as they are ready rather than waiting for the entire render to complete.

##### renderToPipeableStream

`renderToPipeableStream` is a streaming method that utilizes [Node.js Streams](https://nodejs.org/api/stream.html) to render your application. If you are not using Node, you should look to [renderToReadableStream](#rendertoreadablestream) instead.

```jsx
import { renderToPipeableStream } from 'preact-render-to-string/stream-node';

// Request handler syntax and form will vary across frameworks
function handler(req, res) {
	const { pipe, abort } = renderToPipeableStream(<App />, {
		onShellReady() {
			res.statusCode = 200;
			res.setHeader('Content-Type', 'text/html');
			pipe(res);
		},
		onError(error) {
			res.statusCode = 500;
			res.send(
				`<!doctype html><p>An error ocurred:</p><pre>${error.message}</pre>`
			);
		}
	});

	// Abandon and switch to client rendering if enough time passes.
	setTimeout(abort, 2000);
}
```

##### renderToReadableStream

`renderToReadableStream` is another streaming method and similar to `renderToPipeableStream`, but designed for use in environments that support standardized [Web Streams](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API) instead.

```jsx
import { renderToReadableStream } from 'preact-render-to-string/stream';

// Request handler syntax and form will vary across frameworks
function handler(req, res) {
	const stream = renderToReadableStream(<App />);

	return new Response(stream, {
		headers: {
			'Content-Type': 'text/html'
		}
	});
}
```

#### Customize Renderer Output

We offer a number of options through the `/jsx` module to customize the output of the renderer for a handful of popular use cases.

##### JSX Mode

The JSX rendering mode is especially useful if you're doing any kind of snapshot testing. It renders the output as if it was written in JSX.

```jsx
import renderToString from 'preact-render-to-string/jsx';

const App = <div data-foo={true} />;

const html = renderToString(App, {}, { jsx: true });
console.log(html);
// <div data-foo={true} />
```

##### Pretty Mode

If you need to get the rendered output in a more human friendly way, we've got you covered! By passing the `pretty` option, we'll preserve whitespace and indent the output as expected.

```jsx
import renderToString from 'preact-render-to-string/jsx';

const Foo = () => <div>foo</div>;
const App = (
	<div class="foo">
		<Foo />
	</div>
);

const html = renderToString(App, {}, { pretty: true });
console.log(html);
// <div class="foo">
//   <div>foo</div>
// </div>
```

##### Shallow Mode

For some purposes it's often preferable to not render the whole tree, but only one level. For that we have a shallow renderer which will print child components by name, instead of their return value.

```jsx
import renderToString from 'preact-render-to-string/jsx';

const Foo = () => <div>foo</div>;
const App = (
	<div class="foo">
		<Foo />
	</div>
);

const html = renderToString(App, {}, { shallow: true });
console.log(html);
// <div class="foo"><Foo /></div>
```

##### XML Mode

For elements without children, XML mode will instead render them as self-closing tags.

```jsx
import renderToString from 'preact-render-to-string/jsx';

const Foo = () => <div></div>;
const App = (
	<div class="foo">
		<Foo />
	</div>
);

let html = renderToString(App, {}, { xml: true });
console.log(html);
// <div class="foo"><div /></div>

html = renderToString(App, {}, { xml: false });
console.log(html);
// <div class="foo"><div></div></div>
```

------

**Description:** Preact has several option hooks that allow you to attach callbacks to various stages of the diffing process

### Option Hooks

Callbacks for plugins that can change Preact's rendering.

Preact supports a number of different callbacks that can be used to observe or change each stage of the rendering process, commonly referred to as "Option Hooks" (not to be confused with [hooks](/guide/v10/hooks)). These are frequently used to extend the feature-set of Preact itself, or to create specialized testing tools. All of our addons like `preact/hooks`, `preact/compat` and our devtools extension are based on these callbacks.

This API is primarily intended for tooling or library authors who wish to extend Preact.



#### Versioning and Support

Option Hooks are shipped in Preact, and as such are semantically versioned. However, they do not have the same deprecation policy, which means major versions can change the API without an extended announcement period leading up to release. This is also true for the structure of internal APIs exposed through Options Hooks, like `VNode` objects.

#### Setting Option Hooks

You can set Options Hooks in Preact by modifying the exported `options` object.

When defining a hook, always make sure to call a previously defined hook of that name if there was one. Without this, the callchain will be broken and code that depends on the previously-installed hook will break, resulting in addons like `preact/hooks` or DevTools ceasing to work. Make sure to pass the same arguments to the original hook, too - unless you have a specific reason to change them.

```js
import { options } from 'preact';

// Store previous hook
const oldHook = options.vnode;

// Set our own options hook
options.vnode = vnode => {
	console.log("Hey I'm a vnode", vnode);

	// Call previously defined hook if there was any
	if (oldHook) {
		oldHook(vnode);
	}
};
```

None of the currently available hooks excluding `options.event` have return values, so handling return values from the original hook is not necessary.

#### Available Option Hooks

###### `options.vnode`

**Signature:** `(vnode: VNode) => void`

The most common Options Hook, `vnode` is invoked whenever a VNode object is created. VNodes are Preact's representation of Virtual DOM elements, commonly thought of as "JSX Elements".

###### `options.unmount`

**Signature:** `(vnode: VNode) => void`

Invoked immediately before a vnode is unmounted, when its DOM representation is still attached.

###### `options.diffed`

**Signature:** `(vnode: VNode) => void`

Invoked immediately after a vnode is rendered, once its DOM representation is constructed or transformed into the correct state.

###### `options.event`

**Signature:** `(event: Event) => any`

Invoked just before a DOM event is handled by its associated Virtual DOM listener. When `options.event` is set, the event which is event listener argument is replaced return value of `options.event`.

###### `options.requestAnimationFrame`

**Signature:** `(callback: () => void) => void`

Controls the scheduling of effects and effect-based based functionality in `preact/hooks`.

###### `options.debounceRendering`

**Signature:** `(callback: () => void) => void`

A timing "deferral" function that is used to batch processing of updates in the global component rendering queue.

By default, Preact uses a zero duration `setTimeout`.

###### `options.useDebugValue`

**Signature:** `(value: string | number) => void`

Called when the `useDebugValue` hook in `preact/hooks` is called.

------

**Description:** Preact has built-in TypeScript support. Learn how to make use of it!

### TypeScript

Preact ships TypeScript type definitions, which are used by the library itself!

When you use Preact in a TypeScript-aware editor (like VSCode), you can benefit from the added type information while writing regular JavaScript. If you want to add type information to your own applications, you can use [JSDoc annotations](https://fettblog.eu/typescript-jsdoc-superpowers/), or write TypeScript and transpile to regular JavaScript. This section will focus on the latter.



#### TypeScript configuration

TypeScript includes a full-fledged JSX compiler that you can use instead of Babel. Add the following configuration to your `tsconfig.json` to transpile JSX to Preact-compatible JavaScript:

```json
// Classic Transform
{
	"compilerOptions": {
		"jsx": "react",
		"jsxFactory": "h",
		"jsxFragmentFactory": "Fragment"
		//...
	}
}
```

```json
// Automatic Transform, available in TypeScript >= 4.1.1
{
	"compilerOptions": {
		"jsx": "react-jsx",
		"jsxImportSource": "preact"
		//...
	}
}
```

If you use TypeScript within a Babel toolchain, set `jsx` to `preserve` and let Babel handle the transpilation. You still need to specify `jsxFactory` and `jsxFragmentFactory` to get the correct types.

```json
{
	"compilerOptions": {
		"jsx": "preserve",
		"jsxFactory": "h",
		"jsxFragmentFactory": "Fragment"
		//...
	}
}
```

In your `.babelrc`:

```javascript
{
  presets: [
    "@babel/env",
    ["@babel/typescript", { jsxPragma: "h" }],
  ],
  plugins: [
    ["@babel/transform-react-jsx", { pragma: "h" }]
  ],
}
```

Rename your `.jsx` files to `.tsx` for TypeScript to correctly parse your JSX.

#### TypeScript preact/compat configuration

Your project could need support for the wider React ecosystem. To make your application
compile, you might need to disable type checking on your `node_modules` and add paths to the types
like this. This way, your alias will work properly when libraries import React.

```json
{
  "compilerOptions": {
    ...
    "skipLibCheck": true,
    "baseUrl": "./",
    "paths": {
      "react": ["./node_modules/preact/compat/"],
      "react/jsx-runtime": ["./node_modules/preact/jsx-runtime"],
      "react-dom": ["./node_modules/preact/compat/"],
      "react-dom/*": ["./node_modules/preact/compat/*"]
    }
  }
}
```

#### Typing components

There are different ways to type components in Preact. Class components have generic type variables to ensure type safety. TypeScript sees a function as functional component as long as it returns JSX. There are multiple solutions to define props for functional components.

##### Function components

Typing regular function components is as easy as adding type information to the function arguments.

```tsx
interface MyComponentProps {
	name: string;
	age: number;
}

function MyComponent({ name, age }: MyComponentProps) {
	return (
		<div>
			My name is {name}, I am {age.toString()} years old.
		</div>
	);
}
```

You can set default props by setting a default value in the function signature.

```tsx
interface GreetingProps {
	name?: string; // name is optional!
}

function Greeting({ name = 'User' }: GreetingProps) {
	// name is at least "User"
	return <div>Hello {name}!</div>;
}
```

Preact also ships a `FunctionComponent` type to annotate anonymous functions. `FunctionComponent` also adds a type for `children`:

```tsx
import { h, FunctionComponent } from 'preact';

const Card: FunctionComponent<{ title: string }> = ({ title, children }) => {
	return (
		<div class="card">
			<h1>{title}</h1>
			{children}
		</div>
	);
};
```

`children` is of type `ComponentChildren`. You can specify children on your own using this type:

```tsx
import { h, ComponentChildren } from 'preact';

interface ChildrenProps {
	title: string;
	children: ComponentChildren;
}

function Card({ title, children }: ChildrenProps) {
	return (
		<div class="card">
			<h1>{title}</h1>
			{children}
		</div>
	);
}
```

##### Class components

Preact's `Component` class is typed as a generic with two generic type variables: Props and State. Both types default to the empty object, and you can specify them according to your needs.

```tsx
// Types for props
interface ExpandableProps {
	title: string;
}

// Types for state
interface ExpandableState {
	toggled: boolean;
}

// Bind generics to ExpandableProps and ExpandableState
class Expandable extends Component<ExpandableProps, ExpandableState> {
	constructor(props: ExpandableProps) {
		super(props);
		// this.state is an object with a boolean field `toggle`
		// due to ExpandableState
		this.state = {
			toggled: false
		};
	}
	// `this.props.title` is string due to ExpandableProps
	render() {
		return (
			<div class="expandable">
				<h2>
					{this.props.title}{' '}
					<button
						onClick={() => this.setState({ toggled: !this.state.toggled })}
					>
						Toggle
					</button>
				</h2>
				<div hidden={this.state.toggled}>{this.props.children}</div>
			</div>
		);
	}
}
```

Class components include children by default, typed as `ComponentChildren`.

#### Inheriting HTML properties

When we write components like `<Input />` that wrap the HTML `<input>`, most of the time we'd want to inherit
the props that can be used on the native HTML input element. To do this we can do the following:

```tsx
import { JSX } from 'preact';

interface InputProperties extends JSX.InputHTMLAttributes<HTMLInputElement> {
	mySpecialProp: any;
}

const Input = (props: InputProperties) => <input {...props} />;
```

Now when we use `Input` it will know about properties like `value`, ...

#### Typing events

Preact emits regular DOM events. As long as your TypeScript project includes the `dom` library (set it in `tsconfig.json`), you have access to all event types that are available in your current configuration.

```tsx
import type { JSX } from "preact";

export class Button extends Component {
  handleClick(event: JSX.TargetedMouseEvent<HTMLButtonElement>) {
    alert(event.currentTarget.tagName); // Alerts BUTTON
  }

  render() {
    return (
      <button onClick={this.handleClick}>
        {this.props.children}
      </button>
    );
  }
}
```

If you prefer inline functions, you can forgo explicitly typing the current event target as it is inferred from the JSX element:

```tsx
export class Button extends Component {
	render() {
		return (
			<button onClick={event => alert(event.currentTarget.tagName)}>
				{this.props.children}
			</button>
		);
	}
}
```

#### Typing references

The `createRef` function is also generic, and lets you bind references to element types. In this example, we ensure that the reference can only be bound to `HTMLAnchorElement`. Using `ref` with any other element lets TypeScript thrown an error:

```tsx
import { h, Component, createRef } from 'preact';

class Foo extends Component {
	ref = createRef<HTMLAnchorElement>();

	componentDidMount() {
		// current is of type HTMLAnchorElement
		console.log(this.ref.current);
	}

	render() {
		return <div ref={this.ref}>Foo</div>;
		//          ~~~
		//       💥 Error! Ref only can be used for HTMLAnchorElement
	}
}
```

This helps a lot if you want to make sure that the elements you `ref` to are input elements that can be e.g. focussed.

#### Typing context

`createContext` tries to infer as much as possible from the initial values you pass to:

```tsx
import { h, createContext } from 'preact';

const AppContext = createContext({
	authenticated: true,
	lang: 'en',
	theme: 'dark'
});
// AppContext is of type preact.Context<{
//   authenticated: boolean;
//   lang: string;
//   theme: string;
// }>
```

It also requires you to pass in all the properties you defined in the initial value:

```tsx
function App() {
	// This one errors 💥 as we haven't defined theme
	return (
		<AppContext.Provider
			value={{
	 //    ~~~~~
	 // 💥 Error: theme not defined
				lang: 'de',
				authenticated: true
			}}
		>
			{}
			<ComponentThatUsesAppContext />
		</AppContext.Provider>
	);
}
```

If you don't want to specify all properties, you can either merge default values with overrides:

```tsx
const AppContext = createContext(appContextDefault);

function App() {
	return (
		<AppContext.Provider
			value={{
				lang: 'de',
				...appContextDefault
			}}
		>
			<ComponentThatUsesAppContext />
		</AppContext.Provider>
	);
}
```

Or you work without default values and use bind the generic type variable to bind context to a certain type:

```tsx
interface AppContextValues {
  authenticated: boolean;
  lang: string;
  theme: string;
}

const AppContext = createContext<Partial<AppContextValues>>({});

function App() {
  return (
    <AppContext.Provider
      value={{
        lang: "de"
      }}
    >
      <ComponentThatUsesAppContext />
    </AppContext.Provider>
  );
```

All values become optional, so you have to do null checks when using them.

#### Typing hooks

Most hooks don't need any special typing information, but can infer types from usage.

##### useState, useEffect, useContext

`useState`, `useEffect` and `useContext` all feature generic types so you don't need to annotate extra. Below is a minimal component that uses `useState`, with all types inferred from the function signature's default values.

```tsx
const Counter = ({ initial = 0 }) => {
	// since initial is a number (default value!), clicks is a number
	// setClicks is a function that accepts
	// - a number
	// - a function returning a number
	const [clicks, setClicks] = useState(initial);
	return (
		<>
			<p>Clicks: {clicks}</p>
			<button onClick={() => setClicks(clicks + 1)}>+</button>
			<button onClick={() => setClicks(clicks - 1)}>-</button>
		</>
	);
};
```

`useEffect` does extra checks so you only return cleanup functions.

```typescript
useEffect(() => {
	const handler = () => {
		document.title = window.innerWidth.toString();
	};
	window.addEventListener('resize', handler);

	// ✅  if you return something from the effect callback
	// it HAS to be a function without arguments
	return () => {
		window.removeEventListener('resize', handler);
	};
});
```

`useContext` gets the type information from the default object you pass into `createContext`.

```tsx
const LanguageContext = createContext({ lang: 'en' });

const Display = () => {
	// lang will be of type string
	const { lang } = useContext(LanguageContext);
	return (
		<>
			<p>Your selected language: {lang}</p>
		</>
	);
};
```

##### useRef

Just like `createRef`, `useRef` benefits from binding a generic type variable to a subtype of `HTMLElement`. In the example below, we make sure that `inputRef` only can be passed to `HTMLInputElement`. `useRef` is usually initialized with `null`, with the `strictNullChecks` flag enabled, we need to check if `inputRef` is actually available.

```tsx
import { h } from 'preact';
import { useRef } from 'preact/hooks';

function TextInputWithFocusButton() {
	// initialise with null, but tell TypeScript we are looking for an HTMLInputElement
	const inputRef = useRef<HTMLInputElement>(null);
	const focusElement = () => {
		// strict null checks need us to check if inputEl and current exist.
		// but once current exists, it is of type HTMLInputElement, thus it
		// has the method focus! ✅
		if (inputRef && inputRef.current) {
			inputRef.current.focus();
		}
	};
	return (
		<>
			{/* in addition, inputEl only can be used with input elements */}
			<input ref={inputRef} type="text" />
			<button onClick={focusElement}>Focus the input</button>
		</>
	);
}
```

##### useReducer

For the `useReducer` hook, TypeScript tries to infer as many types as possible from the reducer function. See for example a reducer for a counter.

```typescript
// The state type for the reducer function
interface StateType {
	count: number;
}

// An action type, where the `type` can be either
// "reset", "decrement", "increment"
interface ActionType {
	type: 'reset' | 'decrement' | 'increment';
}

// The initial state. No need to annotate
const initialState = { count: 0 };

function reducer(state: StateType, action: ActionType) {
	switch (action.type) {
		// TypeScript makes sure we handle all possible
		// action types, and gives auto complete for type
		// strings
		case 'reset':
			return initialState;
		case 'increment':
			return { count: state.count + 1 };
		case 'decrement':
			return { count: state.count - 1 };
		default:
			return state;
	}
}
```

Once we use the reducer function in `useReducer`, we infer several types and do type checks for passed arguments.

```tsx
function Counter({ initialCount = 0 }) {
	// TypeScript makes sure reducer has maximum two arguments, and that
	// the initial state is of type Statetype.
	// Furthermore:
	// - state is of type StateType
	// - dispatch is a function to dispatch ActionType
	const [state, dispatch] = useReducer(reducer, { count: initialCount });

	return (
		<>
			Count: {state.count}
			{/* TypeScript ensures that the dispatched actions are of ActionType */}
			<button onClick={() => dispatch({ type: 'reset' })}>Reset</button>
			<button onClick={() => dispatch({ type: 'increment' })}>+</button>
			<button onClick={() => dispatch({ type: 'decrement' })}>-</button>
		</>
	);
}
```

The only annotation needed is in the reducer function itself. The `useReducer` types also ensure that the return value of the reducer function is of type `StateType`.

#### Extending built-in JSX types

You may have [custom elements](/guide/v10/web-components) that you'd like to use in JSX, or you may wish to add additional attributes to all HTML elements to work with a particular library. To do this, you will need to extend the `IntrinsicElements` or `HTMLAttributes` interfaces, respectively, so that TypeScript is aware and can provide correct type information.

##### Extending `IntrinsicElements`

```tsx
function MyComponent() {
	return <loading-bar showing={true}></loading-bar>;
	//      ~~~~~~~~~~~
	//   💥 Error! Property 'loading-bar' does not exist on type 'JSX.IntrinsicElements'.
}
```

```tsx
// global.d.ts

declare global {
	namespace preact.JSX {
		interface IntrinsicElements {
			'loading-bar': { showing: boolean };
		}
	}
}

// This empty export is important! It tells TS to treat this as a module
export {};
```

##### Extending `HTMLAttributes`

```tsx
function MyComponent() {
	return <div custom="foo"></div>;
	//          ~~~~~~
	//       💥 Error! Type '{ custom: string; }' is not assignable to type 'DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>'.
	//                   Property 'custom' does not exist on type 'DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>'.
}
```

```tsx
// global.d.ts

declare global {
	namespace preact.JSX {
		interface HTMLAttributes {
			custom?: string | undefined;
		}
	}
}

// This empty export is important! It tells TS to treat this as a module
export {};
```

------

**Description:** Whilst build tools like Webpack, Rollup, and Vite are incredibly powerful and useful, Preact fully supports building applications without them

### No-Build Workflows

Whilst build tools like Webpack, Rollup, and Vite are incredibly powerful and useful, Preact fully supports building
applications without them.

No-build workflows are a way to develop web applications while forgoing build tooling, instead relying on the browser
to facilitate module loading and execution. This is a great way to get started with Preact and can continue to work
very well at all scales.



#### Import Maps

An [Import Map](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap) is a newer browser feature
that allows you to control how browsers resolve module specifiers, often to convert bare specifiers such as `preact`
to a CDN URL like `https://esm.sh/preact`. While many do prefer the aesthetics import maps can provide, there are also
objective advantages to the centralization of dependencies such as easier versioning, reduced/removed duplication, and
better access to more powerful CDN features.

We do generally recommend using import maps for those choosing to forgo build tooling as they work around some issues
you may encounter using bare CDN URLs in your import specifiers (more on that below).

##### Basic Usage

[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap) has a great deal of information on how to
utilize import maps, but a basic example looks like the following:

```html
<!DOCTYPE html>
<html>
	<head>
		<script type="importmap">
			{
				"imports": {
					"preact": "https://esm.sh/preact@10.23.1",
					"htm/preact": "https://esm.sh/htm@3.1.1/preact?external=preact"
				}
			}
		</script>
	</head>
	<body>
		<div id="app"></div>

		<script type="module">
			import { render } from 'preact';
			import { html } from 'htm/preact';

			export function App() {
				return html`
					<h1>Hello, World!</h1>
				`;
			}

			render(
				html`<${App} />`,
				document.getElementById('app')
			);
		</script>
	</body>
</html>
```

We create a `<script>` tag with a `type="importmap"` attribute, and then define the modules we'd like to use
inside of it as JSON. Later, in a `<script type="module">` tag, we can import these modules using bare specifiers,
similar to what you'd see in Node.

> **Important:** We use `?external=preact` in the example above as https://esm.sh will helpfully provide the
> module you're asking for as well as its dependencies -- for `htm/preact`, this means also providing a
> copy of `preact`. However, Preact must be used only as a singleton with only a single copy included in your app.
>
> By using `?external=preact`, we tell `esm.sh` that it shouldn't provide a copy of `preact`, we can handle
> that ourselves. Therefore, the browser will use our importmap to resolve `preact`, using the same Preact
> instance as the rest of our code.

##### Recipes and Common Patterns

While not an exhaustive list, here are some common patterns and recipes you may find useful when working with
import maps. If you have a pattern you'd like to see, [let us know](https://github.com/preactjs/preact-www/issues/new)!

For these examples we'll be using https://esm.sh as our CDN -- it's a brilliant, ESM-focused CDN that's a bit
more flexible and powerful than some others, but by no means are you limited to it. However you choose to serve
your modules, make sure you're familiar with the policy regarding dependencies: duplication of `preact` and some
other libraries will cause (often subtle and unexpected) issues. For `esm.sh`, we address this with the `?external`
query parameter, but other CDNs may work differently.

###### Preact with Hooks, Signals, and HTM

```html
<script type="importmap">
	{
		"imports": {
			"preact": "https://esm.sh/preact@10.23.1",
			"preact/": "https://esm.sh/preact@10.23.1/",
			"@preact/signals": "https://esm.sh/@preact/signals@1.3.0?external=preact",
			"htm/preact": "https://esm.sh/htm@3.1.1/preact?external=preact"
		}
	}
</script>
```

###### Aliasing React to Preact

```html
<script type="importmap">
	{
		"imports": {
			"preact": "https://esm.sh/preact@10.23.1",
			"preact/": "https://esm.sh/preact@10.23.1/",
			"react": "https://esm.sh/preact@10.23.1/compat",
			"react/": "https://esm.sh/preact@10.23.1/compat/",
			"react-dom": "https://esm.sh/preact@10.23.1/compat",
			"@mui/material": "https://esm.sh/@mui/material@5.16.7?external=react,react-dom"
		}
	}
</script>
```

#### HTM

Whilst JSX is generally the most popular way to write Preact applications, it requires a build step to convert the non-standard syntax into something browsers and other runtimes can understand natively. Writing `h`/`createElement` calls by hand can be a bit tedious though with less than ideal ergonomics, so we instead recommend a JSX-like alternative called [HTM](https://github.com/developit/htm).

Instead of requiring a build step (though it can use one, see [`babel-plugin-htm`](https://github.com/developit/htm/tree/master/packages/babel-plugin-htm)), HTM uses [Tagged Templates](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#Tagged_templates) syntax, a feature of JavaScript that's been around since 2015 and is supported in all modern browsers. This is an increasingly popular way to write Preact apps and is likely the most popular for those choosing to forgo a build step.

HTM supports all standard Preact features, including Components, Hooks, Signals, etc., the only difference being the syntax used to write the "JSX" return value.

```js

import { render } from 'preact';

import { useState } from 'preact/hooks';
import { html } from 'htm/preact';

function Button({ action, children }) {
	return html`
		<button onClick=${action}>${children}</button>
	`;
}

function Counter() {
	const [count, setCount] = useState(0);

	return html`
		<div class="counter-container">
			<${Button} action=${() => setCount(count + 1)}>Increment<//>
			<input readonly value=${count} />
			<${Button} action=${() => setCount(count - 1)}>Decrement<//>
		</div>
	`;
}

render(
	html`<${Counter} />`,
	document.getElementById('app')
);
```

------

## Libraries

**Description:** preact-iso is a collection of isomorphic async tools for Preact

### preact-iso

preact-iso is a collection of isomorphic async tools for Preact.

"Isomorphic" describes code that can run (ideally seamlessly) across both the browser and server. `preact-iso` is made for supporting these environments, allowing users to build apps without having to create separate browser and server routers or worry about differences in data or component loading. The same app code can be used in the browser and on a server during prerendering, no adjustments necessary.

> **Note:** Whilst this is a routing library that comes from the Preact team, many other routers are available in the wider Preact/React ecosystem that you may prefer to use instead, including [wouter](https://github.com/molefrog/wouter) and [react-router](https://reactrouter.com/). It's a great first option but you can bring your favorite router to Preact if you prefer.



#### Routing

`preact-iso` offers a simple router for Preact with conventional and hooks-based APIs. The `<Router>` component is async-aware: when transitioning from one route to another, if the incoming route suspends (throws a Promise), the outgoing route is preserved until the new one becomes ready.

```jsx
import {
	lazy,
	LocationProvider,
	ErrorBoundary,
	Router,
	Route
} from 'preact-iso';

// Synchronous
import Home from './routes/home.js';

// Asynchronous (throws a promise)
const Profiles = lazy(() => import('./routes/profiles.js'));
const Profile = lazy(() => import('./routes/profile.js'));
const NotFound = lazy(() => import('./routes/_404.js'));

function App() {
	return (
		<LocationProvider>
			<ErrorBoundary>
				<Router>
					<Home path="/" />
					{/* Alternative dedicated route component for better TS support */}
					<Route path="/profiles" component={Profiles} />
					<Route path="/profile/:id" component={Profile} />
					{/* `default` prop indicates a fallback route. Useful for 404 pages */}
					<NotFound default />
				</Router>
			</ErrorBoundary>
		</LocationProvider>
	);
}
```

**Progressive Hydration:** When the app is hydrated on the client, the route (`Home` or `Profile` in this case) suspends. This causes hydration for that part of the page to be deferred until the route's `import()` is resolved, at which point that part of the page automatically finishes hydrating.

**Seamless Routing:** When switching between routes on the client, the Router is aware of asynchronous dependencies in routes. Instead of clearing the current route and showing a loading spinner while waiting for the next route, the router preserves the current route in-place until the incoming route has finished loading, then they are swapped.

#### Prerendering

`prerender()` renders a Virtual DOM tree to an HTML string using [`preact-render-to-string`](https://github.com/preactjs/preact-render-to-string). The Promise returned from `prerender()` resolves to an Object with `html` and `links[]` properties. The `html` property contains your pre-rendered static HTML markup, and `links` is an Array of any non-external URL strings found in links on the generated page.

Primarily meant for use with prerendering via [`@preact/preset-vite`](https://github.com/preactjs/preset-vite#prerendering-configuration) or other prerendering systems that share the API. If you're server-side rendering your app via any other method, you can use `preact-render-to-string` (specifically `renderToStringAsync()`) directly.

```jsx
import {
	LocationProvider,
	ErrorBoundary,
	Router,
	lazy,
	prerender as ssr
} from 'preact-iso';

// Asynchronous (throws a promise)
const Foo = lazy(() => import('./foo.js'));

function App() {
	return (
		<LocationProvider>
			<ErrorBoundary>
				<Router>
					<Foo path="/" />
				</Router>
			</ErrorBoundary>
		</LocationProvider>
	);
}

hydrate(<App />);

export async function prerender(data) {
	return await ssr(<App />);
}
```

#### Nested Routing

Nested routes are supported by using multiple `Router` components. Partially matched routes end with a wildcard (`/*`) and the remaining value will be passed to continue matching with if there are any further routes.

```jsx
import {
	lazy,
	LocationProvider,
	ErrorBoundary,
	Router,
	Route
} from 'preact-iso';

const NotFound = lazy(() => import('./routes/_404.js'));

function App() {
	return (
		<LocationProvider>
			<ErrorBoundary>
				<Router>
					<Route path="/movies/*" component={Movies} />
					<NotFound default />
				</Router>
			</ErrorBoundary>
		</LocationProvider>
	);
}

const TrendingMovies = lazy(() => import('./routes/movies/trending.js'));
const SearchMovies = lazy(() => import('./routes/movies/search.js'));
const MovieDetails = lazy(() => import('./routes/movies/details.js'));

function Movies() {
	return (
		<ErrorBoundary>
			<Router>
				<Route path="/trending" component={TrendingMovies} />
				<Route path="/search" component={SearchMovies} />
				<Route path="/:id" component={MovieDetails} />
			</Router>
		</ErrorBoundary>
	);
}
```

This will match the following routes:

- `/movies/trending`
- `/movies/search`
- `/movies/Inception`

---

#### API Docs

##### LocationProvider

A context provider that provides the current location to its children. This is required for the router to function.

Props:

- `scope?: string | RegExp` - Sets a scope for the paths that the router will handle (intercept). If a path does not match the scope, either by starting with the provided string or matching the RegExp, the router will ignore it and default browser navigation will apply.

Typically, you would wrap your entire app in this provider:

```jsx
import { LocationProvider } from 'preact-iso';

function App() {
	return (
		<LocationProvider scope="/app">{/* Your app here */}</LocationProvider>
	);
}
```

##### Router

Props:

- `onRouteChange?: (url: string) => void` - Callback to be called when a route changes.
- `onLoadStart?: (url: string) => void` - Callback to be called when a route starts loading (i.e., if it suspends). This will not be called before navigations to sync routes or subsequent navigations to async routes.
- `onLoadEnd?: (url: string) => void` - Callback to be called after a route finishes loading (i.e., if it suspends). This will not be called after navigations to sync routes or subsequent navigations to async routes.

```jsx
import { LocationProvider, Router } from 'preact-iso';

function App() {
	return (
		<LocationProvider>
			<Router
				onRouteChange={url => console.log('Route changed to', url)}
				onLoadStart={url => console.log('Starting to load', url)}
				onLoadEnd={url => console.log('Finished loading', url)}
			>
				<Home path="/" />
				<Profiles path="/profiles" />
				<Profile path="/profile/:id" />
			</Router>
		</LocationProvider>
	);
}
```

##### Route

There are two ways to define routes using `preact-iso`:

1. Append router params to the route components directly: `<Home path="/" />`
2. Use the `Route` component instead: `<Route path="/" component={Home} />`

Appending arbitrary props to components not unreasonable in JavaScript, as JS is a dynamic language that's perfectly happy to support dynamic & arbitrary interfaces. However, TypeScript, which many of us use even when writing JS (via TS's language server), is not exactly a fan of this sort of interface design.

TS does not (yet) allow for overriding a child's props from the parent component so we cannot, for instance, define `<Home>` as taking no props _unless_ it's a child of a `<Router>`, in which case it can have a `path` prop. This leaves us with a bit of a dilemma: either we define all of our routes as taking `path` props so we don't see TS errors when writing `<Home path="/" />` or we create wrapper components to handle the route definitions.

While `<Home path="/" />` is completely equivalent to `<Route path="/" component={Home} />`, TS users may find the latter preferable.

```jsx
import { LocationProvider, Router, Route } from 'preact-iso';

function App() {
	return (
		<LocationProvider>
			<Router>
				{/* Both of these are equivalent */}
				<Home path="/" />
				<Route path="/" component={Home} />

				<Profiles path="/profiles" />
				<Profile path="/profile/:id" />
				<NotFound default />
			</Router>
		</LocationProvider>
	);
}
```

Props for any route component:

- `path: string` - The path to match (read on)
- `default?: boolean` - If set, this route is a fallback/default route to be used when nothing else matches

Specific to the `Route` component:

- `component: AnyComponent` - The component to render when the route matches

###### Path Segment Matching

Paths are matched using a simple string matching algorithm. The following features may be used:

- `:param` - Matches any URL segment, binding the value to the label (can later extract this value from `useRoute()`)
  - `/profile/:id` will match `/profile/123` and `/profile/abc`
  - `/profile/:id?` will match `/profile` and `/profile/123`
  - `/profile/:id*` will match `/profile`, `/profile/123`, and `/profile/123/abc`
  - `/profile/:id+` will match `/profile/123`, `/profile/123/abc`
- `*` - Matches one or more URL segments
  - `/profile/*` will match `/profile/123`, `/profile/123/abc`, etc.

These can then be composed to create more complex routes:

- `/profile/:id/*` will match `/profile/123/abc`, `/profile/123/abc/def`, etc.

The difference between `/:id*` and `/:id/*` is that in the former, the `id` param will include the entire path after it, while in the latter, the `id` is just the single path segment.

- `/profile/:id*`, with `/profile/123/abc`
  - `id` is `123/abc`
- `/profile/:id/*`, with `/profile/123/abc`
  - `id` is `123`

##### useLocation()

A hook to work with the `LocationProvider` to access location context.

Returns an object with the following properties:

- `url: string` - The current path & search params
- `path: string` - The current path
- `query: Record<string, string>` - The current query string parameters (`/profile?name=John` -> `{ name: 'John' }`)
- `route: (url: string, replace?: boolean) => void` - A function to programmatically navigate to a new route. The `replace` param can optionally be used to overwrite history, navigating them away without keeping the current location in the history stack.

##### useRoute()

A hook to access current route information. Unlike `useLocation`, this hook only works within `<Router>` components.

Returns an object with the following properties:

- `path: string` - The current path
- `query: Record<string, string>` - The current query string parameters (`/profile?name=John` -> `{ name: 'John' }`)
- `params: Record<string, string>` - The current route parameters (`/profile/:id` -> `{ id: '123' }`)

##### lazy()

Make a lazily-loaded version of a Component.

`lazy()` takes an async function that resolves to a Component, and returns a wrapper version of that Component. The wrapper component can be rendered right away, even though the component is only loaded the first time it is rendered.

```jsx
import { lazy, LocationProvider, Router } from 'preact-iso';

// Synchronous, not code-splitted:
import Home from './routes/home.js';

// Asynchronous, code-splitted:
const Profiles = lazy(() =>
	import('./routes/profiles.js').then(m => m.Profiles)
); // Expects a named export called `Profiles`
const Profile = lazy(() => import('./routes/profile.js')); // Expects a default export

function App() {
	return (
		<LocationProvider>
			<Router>
				<Home path="/" />
				<Profiles path="/profiles" />
				<Profile path="/profile/:id" />
			</Router>
		</LocationProvider>
	);
}
```

The result of `lazy()` also exposes a `preload()` method that can be used to load the component before it's needed for rendering. Entirely optional, but can be useful on focus, mouse over, etc. to start loading the component a bit earlier than it otherwise would be.

```jsx
const Profile = lazy(() => import('./routes/profile.js'));

function Home() {
	return (
		<a href="/profile/rschristian" onMouseOver={() => Profile.preload()}>
			Profile Page -- Hover over me to preload the module!
		</a>
	);
}
```

##### ErrorBoundary

A simple component to catch errors in the component tree below it.

Props:

- `onError?: (error: Error) => void` - A callback to be called when an error is caught

```jsx
import { LocationProvider, ErrorBoundary, Router } from 'preact-iso';

function App() {
	return (
		<LocationProvider>
			<ErrorBoundary onError={e => console.log(e)}>
				<Router>
					<Home path="/" />
					<Profiles path="/profiles" />
					<Profile path="/profile/:id" />
				</Router>
			</ErrorBoundary>
		</LocationProvider>
	);
}
```

##### hydrate()

A thin wrapper around Preact's `hydrate` export, it switches between hydrating and rendering the provided element, depending on whether the current page has been prerendered. Additionally, it checks to ensure it's running in a browser context before attempting any rendering, making it a no-op during SSR.

Pairs with the `prerender()` function.

Params:

- `jsx: ComponentChild` - The JSX element or component to render
- `parent?: Element | Document | ShadowRoot | DocumentFragment` - The parent element to render into. Defaults to `document.body` if not provided.

```jsx
import { hydrate } from 'preact-iso';

function App() {
	return (
		<div class="app">
			<h1>Hello World</h1>
		</div>
	);
}

hydrate(<App />);
```

However, it is just a simple utility method. By no means is it essential to use, you can always use Preact's `hydrate` export directly.

##### prerender()

Renders a Virtual DOM tree to an HTML string using `preact-render-to-string`. The Promise returned from `prerender()` resolves to an Object with `html` and `links[]` properties. The `html` property contains your pre-rendered static HTML markup, and `links` is an Array of any non-external URL strings found in links on the generated page.

Pairs primarily with [`@preact/preset-vite`](https://github.com/preactjs/preset-vite#prerendering-configuration)'s prerendering.

Params:

- `jsx: ComponentChild` - The JSX element or component to render

```jsx
import {
	LocationProvider,
	ErrorBoundary,
	Router,
	lazy,
	prerender
} from 'preact-iso';

// Asynchronous (throws a promise)
const Foo = lazy(() => import('./foo.js'));
const Bar = lazy(() => import('./bar.js'));

function App() {
	return (
		<LocationProvider>
			<ErrorBoundary>
				<Router>
					<Foo path="/" />
					<Bar path="/bar" />
				</Router>
			</ErrorBoundary>
		</LocationProvider>
	);
}

const { html, links } = await prerender(<App />);
```

------

**Description:** Wrap your Preact component up as a custom element

### preact-custom-element

Preact's tiny size and standards-first approach make it a great choice for building web components.

Preact is designed to render both full applications and individual parts of a page, making it a natural fit for building Web Components. Many companies use this approach to build component or design systems that are then wrapped up into a set of Web Components, enabling re-use across multiple projects and within other frameworks whilst continuing to offer the familiar Preact APIs.



#### Creating a Web Component

Any Preact component can be turned into a web component with [preact-custom-element](https://github.com/preactjs/preact-custom-element), a very thin wrapper that adheres to the Custom Elements v1 spec.

```jsx
import register from 'preact-custom-element';

const Greeting = ({ name = 'World' }) => <p>Hello, {name}!</p>;

register(Greeting, 'x-greeting', ['name'], { shadow: false });
//          ^            ^           ^             ^
//          |      HTML tag name     |       use shadow-dom
//   Component definition      Observed attributes
```

> Note: As per the [Custom Element Specification](http://w3c.github.io/webcomponents/spec/custom/#prod-potentialcustomelementname), the tag name must contain a hyphen (`-`).

Use the new tag name in HTML, attribute keys and values will be passed in as props:

```html
<x-greeting name="Billy Jo"></x-greeting>
```

Output:

```html
<p>Hello, Billy Jo!</p>
```

##### Observed Attributes

Web Components require explicitly listing the names of attributes you want to observe in order to respond when their values are changed. These can be specified via the third parameter that's passed to the `register()` function:

```jsx
// Listen to changes to the `name` attribute
register(Greeting, 'x-greeting', ['name']);
```

If you omit the third parameter to `register()`, the list of attributes to observe can be specified using a static `observedAttributes` property on your Component. This also works for the Custom Element's name, which can be specified using a `tagName` static property:

```jsx
import register from 'preact-custom-element';

// <x-greeting name="Bo"></x-greeting>
class Greeting extends Component {
	// Register as <x-greeting>:
	static tagName = 'x-greeting';

	// Track these attributes:
	static observedAttributes = ['name'];

	render({ name }) {
		return <p>Hello, {name}!</p>;
	}
}
register(Greeting);
```

If no `observedAttributes` are specified, they will be inferred from the keys of `propTypes` if present on the Component:

```jsx
// Other option: use PropTypes:
function FullName({ first, last }) {
	return (
		<span>
			{first} {last}
		</span>
	);
}

FullName.propTypes = {
	first: Object, // you can use PropTypes, or this
	last: Object // trick to define un-typed props.
};

register(FullName, 'full-name');
```

##### Passing slots as props

The `register()` function has a fourth parameter to pass options; currently, only the `shadow` option is supported, which attaches a shadow DOM tree to the specified element. When enabled, this allows the use of named `<slot>` elements to forward the Custom Element's children to specific places in the shadow tree.

```jsx
function TextSection({ heading, content }) {
	return (
		<div>
			<h1>{heading}</h1>
			<p>{content}</p>
		</div>
	);
}

register(TextSection, 'text-section', [], { shadow: true });
```

Usage:

```html
<text-section>
	<span slot="heading">Nice heading</span>
	<span slot="content">Great content</span>
</text-section>
```

------