# Preact

> 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 re

---

# Source: https://preactjs.com/guide/v10/components#error-boundaries

# Source: https://preactjs.com/guide/v10/components#fragments

# 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)
* [Class Components](#class-components)
    * [Lifecycle Methods](#lifecycle-methods)
    * [Error Boundaries](#error-boundaries)
* [Fragments](#fragments)

---

## 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
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
class Clock extends Component {
	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>;
	}
}
```

### 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 after `render()`, but before changes are flushed to the DOM. 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
class ErrorBoundary extends Component {
	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;
	}
}
```

### 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.
				key: item.id,
				<dt>{item.term}</dt>
				<dd>{item.description}</dd>
			}))
		</dl>
	);
}
```

---

# Source: https://preactjs.com/guide/v10/context#createcontext

# 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).

```jsx
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>
	);
}
```

```jsx
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>
	);
}
```

```jsx
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>
	);
}
```

#### 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
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>
	);
}
```

---

### 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** receive 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
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>
		);
	}
}
```

```bash
Run in REPL

---

# Source: https://preactjs.com/guide/v10/debugging

# 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](https://preactjs.github.io/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](https://preactjs.github.io/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 to 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
<button onClick={() => console.log("click")}>click</button>

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

### 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 child 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>;
```

---

# Source: https://preactjs.com/guide/v10/differences-to-react#features-exclusive-to-preactcompat

# 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](/guide/v10/getting-started#aliasing-react-to-preact), 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](#main-differences)
*   [Version Compatibility](#version-compatibility)
*   [Debug messages and errors](#debug-messages-and-errors)
*   [Features unique to Preact](#features-unique-to-preact)
    *   [Native support for ES Modules](#native-support-for-es-modules)
    *   [Arguments in `Component.render()`](#arguments-in-componentrender)
    *   [Raw HTML attribute/property names](#raw-html-attributeproperty-names)
    *   [SVG inside JSX](#svg-inside-jsx)
    *   [Use `onInput` instead of `onChange`](#use-oninput-instead-of-onchange)
    *   [JSX Constructor](#jsx-constructor)
    *   [No contextTypes needed](#no-contexttypes-needed)

---

## 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](https://developer.mozilla.org/en-US/docs/Web/Events) 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](/guide/v10/getting-started#aliasing-react-to-preact), 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](/about/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 guides 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](/guide/v10/getting-started#aliasing-react-to-preact) 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](/guide/v10/getting-started#aliasing-react-to-preact), 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](https://github.com/dominictarr/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: '/' },
	h('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.

---

# Source: https://preactjs.com/guide/v10/getting-started#aliasing-react-to-preact

# 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](https://github.com/developit/htm).

[HTM](https://github.com/developit/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:
> 
> ```javascript
> 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](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.

---

# Source: https://preactjs.com/guide/v10/hooks

# Hooks

The Hooks API is an alternative way to write components in Preact. Hooks allow you to compose behaviors together and reuse that 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
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>
    );
  }
}
```

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

```jsx
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>
  );
}
```

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
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>
  );
}
```

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 { useState } from 'preact/hooks';

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

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={increment}>+1</button>
      <button onClick={decrement}>-1</button>
      <button onClick={increment}>reset</button>
    </div>
  );
};
```

> 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 { 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>
  );
}
```

## 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
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>
    </>
  );
}
```

> 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
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>
  );
}
```

## 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
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>
  );
}
```

## 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
// 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>;
}
```

> 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);

  useEffect(() => {
    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 =UsageId();
  const inputId =UsageId();

  useEffect(() => {
    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 => `${c}`);
  return [count, setCount];
}
```

### 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]);
}
```

---

# Source: https://preactjs.com/guide/v10/options

# 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.

---

## Table of Contents

*   [Versioning and Support](#versioning-and-support)
*   [Setting Option Hooks](#setting-option-hooks)
*   [Available Option Hooks](#available-option-hooks)

---

## 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`.

By default, Preact uses a zero duration `setTimeout`.

### `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.

---

# Source: https://preactjs.com/guide/v10/preact-root-fragment

# preact-root-fragment

preact-root-fragment is a standalone and more flexible Preact 10+ implementation of the deprecated `replaceNode` parameter from Preact 10.

It provides a way to render or hydrate a Preact tree using a subset of the children within the parent element passed to render():

```html
<body>
	<div id="root"> ⬅ we pass this to render() as the parent DOM element...

		<script src="/etc.js"></script>

		<div class="app"> ⬅ ... but we want to use this tree, not the script
			<!-- ... -->
		</div>
</div>
```

---

*   [Why do I need this?](#why-do-i-need-this?)
*   [How it works](#how-it-works)
*   [Multiple Root Elements](#multiple-root-elements)
*   [Preact Version Support](#preact-version-support)

---

## Why do I need this?

This is particularly useful for [partial hydration](https://jasonformat.com/islands-architecture/), which often requires rendering multiple distinct Preact trees into the same parent DOM element. Imagine the scenario below - which elements would we pass to `hydrate(jsx, parent)` such that each widget's `<section>` would get hydrated without clobbering the others?

```html
<div id="sidebar">
  <section id="widgetA"><h1>Widget A</h1></section>
  <section id="widgetB"><h1>Widget B</h1></section>
  <section id="widgetC"><h1>Widget C</h1></section>
</div>
```

Preact 10 provided a somewhat obscure third argument for `render` and `hydrate` called `replaceNode`, which could be used for the above case:

```jsx
render(<A />, sidebar, widgetA); // render into <div id="sidebar">, but only look at <section id="widgetA">
render(<B />, sidebar, widgetB); // same, but only look at widgetB
render(<C />, sidebar, widgetC); // same, but only look at widgetC
```

While the `replaceNode` argument proved useful for handling scenarios like the above, it was limited to a single DOM element and could not accommodate Preact trees with multiple root elements. It also didn't handle updates well when multiple trees were mounted into the same parent DOM element, which turns out to be a key usage scenario.

Going forward, we're providing this functionality as a standalone library called `preact-root-fragment`.

## How it works

`preact-root-fragment` provides a `createRootFragment` function:

```ts
createRootFragment(parent: ContainerNode, children: ContainerNode | ContainerNode[])
```

Calling this function with a parent DOM element and one or more child elements returns a "Persistent Fragment". A persistent fragment is a fake DOM element, which pretends to contain the provided children while keeping them in their existing real parent element. It can be passed to `render()` or `hydrate()` instead of the `parent` argument.

Using the previous example, we can change the deprecated `replaceNode` usage out for `createRootFragment`:

```jsx
import { createRootFragment } from 'preact-root-fragment';

render(<A />, createRootFragment/sidebar, widgetA));
render(<B />, createRootFragment/sidebar, widgetB));
render(<C />, createRootFragment/sidebar, widgetC));
```

Since we're creating separate "Persistent Fragment" parents to pass to each `render()` call, Preact will treat each as an independent Virtual DOM tree.

## Multiple Root Elements

Unlike the `replaceNode` parameter from Preact 10, `createRootFragment` can accept an Array of children that will be used as the root elements when rendering. This is particularly useful when rendering a Virtual DOM tree that produces multiple root elements, such as a Fragment or an Array:

```jsx
import { createRootFragment } from 'preact-root-fragment';
import { render } from 'preact';

function App() {
  return (
    <>
      <h1>Hello world!</h1>
    </>
  );
}

// Use only the last two child elements within <body:
const children = [].slice.call(document.body.children, -2);

render(<App />, createRootFragment/sidebar, children));
```

## Preact Version Support

This library works with Preact 10 and 11.

---

# Source: https://preactjs.com/guide/v10/preact-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](https://preactjs.com/guide/v10/unit-testing-with-enzyme), Preact Testing Library must be called inside a DOM environment.

---

*   [Installation](#installation)
*   [Usage](#usage)
*   [Finding Elements](#finding-elements)
    *   [Using Content](#using-content)
    *   [Using Test IDs](#using-test-ids)
*   [Debugging Tests](#debugging-tests)
*   [Supplying custom Context Providers](#supplying-custom-context-providers)
*   [Testing Preact Hooks](#testing-preact-hooks)

---

## 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={() => setCount(count + 1)}>
				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'));

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

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

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.

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>
		</vnode>;
}

// 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](https://github.com/testing-library/preact-testing-library).

---

# Source: https://preactjs.com/guide/v10/refs#createref

# Source: https://preactjs.com/guide/v10/refs

# 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](#creating-a-ref)
*   [Using Refs to Access DOM Nodes](#using-refs-to-access-dom-nodes)
    *   [Callback Refs](#callback-refs)
*   [Using Refs to Store Local Values](#using-refs-to-store-local-values)

---

## 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.

### Classes

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

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

  // ...
}
```

### Hooks

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

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

  // ...
}
```

## 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.

### Classes

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

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

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

[Run in REPL](/repl?code=aW1wb3J0IHsgcmVuZGVyLCBDb21wb25lbnQsIGNyZWF0ZVJlZiB9IGZyb20gJ3ByZWFjdCc7CgpjbGFzcyBTaUlucHV0IGV4dGVuZHMgQ29tcG9uZW50IHsKCXJlZiA9IGNyZWF0ZVJlZihudWxsKTsKCgljb21wb25lbnREaWRNb3VudCgpIHsKCQljb25zb2xlLmxvZyh0aGlzLnJlZi5jdXJyZW50KTsKCQkvLyBMb2dzOiBbSFRNTElucHV0RWxlbWVudF0KCX0KCglyZW5kZXIoKSB7CgkJcmV0dXJuIDxpbnB1dCByZWY9e3RoaXMucmVmfSAvPjsKCX0KfQoKcmVuZGVyKDxNeUlucHV0IC8%2BLCBkb2N1bWVudC5nZXRFbGVtZW50QnlJZCgnYXBwJykpOwo%3D)
```

### Hooks

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

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

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

[Run in REPL](/repl?code=aW1wb3J0IHsgcmVuZGVyIH0gZnJvbSAncHJlYWN0JzsKaW1wb3J0IHsgdXNlUmVmLCB1c2VFZmZlY3QgfSBmcm9tICdwcmVhY3QvaG9va3MnOwoKZnVuY3Rpb24gTXlJbnB1dCgpIHsKCWNvbnN0IHJlZiA9IHVzZVJlZihudWxsKTsKCgl1c2VFZmZlY3QoKCkgPT4gewoJCWNvbnNvbGUubG9nKHJlZi5jdXJyZW50KTsKCQkvLyBMb2dzOiBbSFRNTElucHV0RWxlbWVudF0KCX0sIFtdKTsKCglyZXR1cm4gPGlucHV0IHJlZj17cmVmfSAvPjsKfQoKcmVuZGVyKDxNeUlucHV0IC8%2BLCBkb2N1bWVudC5nZXRFbGVtZW50QnlJZCgnYXBwJykpOwo%3D)

### 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.

#### Classes

```jsx
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);
          };
        }}
      />
    );
  }
}

[Run in REPL](/repl?code=aW1wb3J0IHsgcmVuZGVyLCBDb21wb25lbnQgfSBmcm9tICdwcmVhY3QnOwoKY2xhc3MgTXlJbnB1dCBleHRlbmRzIENvbXBvbmVudCB7CglyZW5kZXIoKSB7CgkJcmV0dXJuICgKCQkJPGlucHV0CgkJCQlyZWY9e2RvbSA9PiB7CgkJCQkJY29uc29sZS5sb2coJ01vdW50ZWQ6JywgZG9tKTsKCgkJCQkJLy8gQXMgb2YgUHJlYWN0IDEwLjIzLjAsIHlvdSBjYW4gb3B0aW9uYWxseSByZXR1cm4gYSBjbGVhbnVwIGZ1bmN0aW9uCgkJCQkJcmV0dXJuICgpID0%2BIHsKCQkJCQkJY29uc29sZS5sb2coJ1VubW91bnRlZDonLCBkb20pOwoJCQkJCX07CgkJCQl9fQoJCQkvPgoJCSk7Cgl9Cn0KCnJlbmRlcig8TXlJbnB1dCAvPiwgZG9jdW1lbnQuZ2V0RWxlbWVudEJ5SWQoJ2FwcCcpKTsK)
```

#### Hooks

```jsx
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);
        };
      }}
    />
  );
}
```

[Run in REPL](/repl?code=aW1wb3J0IHsgcmVuZGVyIH0gZnJvbSAncHJlYWN0JzsKCmZ1bmN0aW9uIE15SW5wdXQoKSB7CglyZXR1cm4gKAoJCTxpbnB1dAoJCQlyZWY9e2RvbSA9PiB7CgkJCQljb25zb2xlLmxvZygnTW91bnRlZDonLCBkb20pOwoKCQkJCS8vIEFzIG9mIFByZWFjdCAxMC4yMy4wLCB5b3UgY2FuIG9wdGlvbmFsbHkgcmV0dXJuIGEgY2xlYW51cCBmdW5jdGlvbgoJCQkJcmV0dXJuICgpID0%2BIHsKCQkJCQljb25zb2xlLmxvZygnVW5tb3VudGVkOicsIGRvbSk7CgkJCQl9OwoJCQl9fQoJCS8%2BCgkpOwp9CgpyZW5kZXIoPE15SW5wdXQgLz4sIGRvY3VtZW50LmdldEVsZW1lbnRCeUlkKCdhcHAnKSk7Cg%3D%3D)

> 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.

### Classes

```jsx
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>
    );
  }
}
```

[Run in REPL](/repl?code=aW1wb3J0IHsgcmVuZGVyLCBDb21wb25lbnQsIGNyZWF0ZVJlZiB9IGZyb20gJ3ByZWFjdCc7CgpjbGFzcyBTaW1wbGVDbG9jayBleHRlbmRzIENvbXBvbmVudCB7CglzdGF0ZSA9IHsKCQl0aW1lOiBEYXRlLm5vdygpCgl9OwoJaW50ZXJ2YWxJZCA9IGNyZWF0ZVJlZihudWxsKTsKCglzdGFydENsb2NrID0gKCkgPT4gewoJCXRoaXMuc2V0U3RhdGUoeyB0aW1lOiBEYXRlLm5vdygpIH0pOwoJCXRoaXMuaW50ZXJ2YWxJZC5jdXJyZW50ID0gc2V0SW50ZXJ2YWwoKCkgPT4gewoJCQl0aGlzLnNldFN0YXRlKHsgdGltZTogRGF0ZS5ub3coKSB9KTsKCQl9LCAxMDAwKTsKCX07CgoJc3RvcENsb2NrID0gKCkgPT4gewoJCWNsZWFySW50ZXJ2YWwodGhpcy5pbnRlcnZhbElkLmN1cnJlbnQpOwoJfTsKCglyZW5kZXIoXywgeyB0aW1lIH0pIHsKCQljb25zdCBmb3JtYXR0ZWRUaW1lID0gbmV3IERhdGUodGltZSkudG9Mb2NhbGVUaW1lU3RyaW5nKCk7CgoJCXJldHVybiAoCgkJCTxkaXY%2BCgkJCQk8YnV0dG9uIG9uQ2xpY2s9e3RoaXMuc3RhcnRDbG9ja30%2BU3RhcnQgQ2xvY2s8L2J1dHRvbj4KCQkJCTx0aW1lIGRhdGVUaW1lPXtmb3JtYXR0ZWRUaW1lfT57Zm9ybWF0dGVkVGltZX08L3RpbWU%2BCgkJCQk8YnV0dG9uIG9uQ2xpY2s9e3RoaXMuc3RvcENsb2NrfT5TdG9wIENsb2NrPC9idXR0b24%2BCgkJCTwvZGl2PgoJCSk7Cgl9Cn0KCnJlbmRlcig8U2ltcGxlQ2xvY2sgLz4sIGRvY3VtZW50LmdldEVsZW1lbnRCeUlkKCdhcHAnKSk7Cg%3D%3D)

### Hooks

```jsx
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>
  );
}
```

[Run in REPL](/repl?code=aW1wb3J0IHsgcmVuZGVyIH0gZnJvbSAncHJlYWN0JzsKaW1wb3J0IHsgdXNlU3RhdGUsIHVzZVJlZiB9IGZyb20gJ3ByZWFjdC9ob29rcyc7CgpmdW5jdGlvbiBTaW1wbGVDbG9jaygpIHsKCWNvbnN0IFt0aW1lLCBzZXRUaW1lXSA9IHVzZVN0YXRlKERhdGUubm93KCkpOwoJY29uc3QgaW50ZXJ2YWxJZCA9IHVzZVJlZihudWxsKTsKCgljb25zdCBzdGFydENsb2NrID0gKCkgPT4gewoJCXNldFRpbWUoRGF0ZS5ub3coKSk7CgkJaW50ZXJ2YWxJZC5jdXJyZW50ID0gc2V0SW50ZXJ2YWwoKCkgPT4gewoJCQlzZXRUaW1lKERhdGUubm93KCkpOwoJCX0sIDEwMDApOwoJfTsKCgljb25zdCBzdG9wQ2xvY2sgPSAoKSA9PiB7CgkJY2xlYXJJbnRlcnZhbChpbnRlcnZhbElkLmN1cnJlbnQpOwoJfTsKCgljb25zdCBmb3JtYXR0ZWRUaW1lID0gbmV3IERhdGUodGltZSkudG9Mb2NhbGVUaW1lU3RyaW5nKCk7CgoJcmV0dXJuICgKCQk8ZGl2PgoJCQk8YnV0dG9uIG9uQ2xpY2s9e3N0YXJ0Q2xvY2t9PlN0YXJ0IENsb2NrPC9idXR0b24%2BCgkJCTx0aW1lIGRhdGVUaW1lPXtmb3JtYXR0ZWRUaW1lfT57Zm9ybWF0dGVkVGltZX08L3RpbWU%2BCgkJCTxidXR0b24gb25DbGljaz17c3RvcENsb2NrfT5TdG9wIENsb2NrPC9idXR0b24%2BCgkJPC9kaXY%2BCgkpOwp9CgpyZW5kZXIoPFNpbXBsZUNsb2NrIC8%2BLCBkb2N1bWVudC5nZXRFbGVtZW50QnlJZCgnYXBwJykpOwo%3D)

---

# Source: https://preactjs.com/repl?example=todo-signals

# REPL: Try Preact in the browser – Preact

[We stand with Ukraine. **Show your support** 🇺🇦](https://www.stopputin.net/)

[Preact](/)
[Preact Tutorial](/tutorial)
[Preact Guide](/guide/v10/getting-started)

## About

- [Companies using Preact](/about/we-are-using)
- [Libraries & Add-ons](/about/libraries-addons)
- [Demos & Examples](/about/demos-examples)
- [Project Goals](/about/project-goals)
- [Browser Support](/about/browser-support)

[Blog](/blog)
[REPL](/repl)

Search

[v11.0.0-beta.0](https://github.com/preactjs/preact/releases/tag/11.0.0-beta.0) [](https://github.com/preactjs/preact)[](https://twitter.com/preactjs)[](https://bsky.app/profile/preactjs.com)[](http://chat.preactjs.com/)

Help  
Support Us

---

# Source: https://preactjs.com/guide/v10/server-side-rendering

# 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](#installation)
* [HTML Strings](#html-strings)
  * [renderToString](#rendertostring)
  * [renderToStringAsync](#rendertostringasync)
* [HTML Streams](#html-streams)
  * [renderToPipeableStream](#rendertopipeablestream)
  * [renderToReadableStream](#rendertoreadablestream)
* [Customize Renderer Output](#customize-renderer-output)
  * [JSX Mode](#jsx-mode)
  * [Pretty Mode](#pretty-mode)
  * [Shallow Mode](#shallow-mode)
  * [XML Mode](#xml-mode)

---

## 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 className="foo">{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 occurred:</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>
```

---

# Source: https://preactjs.com/tutorial

# Learn Preact – Preact Tutorial

[We stand with Ukraine. **Show your support** 🇺🇦](https://www.stopputin.net/)

[Preact](https://preactjs.com/)
[Tutorial](https://preactjs.com/tutorial)
[Guide](https://preactjs.com/guide/v10/getting-started)
About
- [Companies using Preact](https://preactjs.com/about/we-are-using)
- [Libraries & Add-ons](https://preactjs.com/about/libraries-addons)
- [Demos & Examples](https://preactjs.com/about/demos-examples)
- [Project Goals](https://preactjs.com/about/project-goals)
- [Browser Support](https://preactjs.com/about/browser-support)
[Blog](https://preactjs.com/blog)
[REPL](https://preactjs.com/repl)

Search

[v11.0.0-beta.0](https://github.com/preactjs/preact/releases/tag/11.0.0-beta.0)
[GitHub](https://github.com/preactjs/preact)
[Twitter](https://twitter.com/preactjs)
[Bluesky](https://bsky.app/profile/preactjs.com)
[Slack](http://chat.preactjs.com/)

Help
Support Us

---

# Source: https://preactjs.com/guide/v10/unit-testing-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](#installation)
*   [Configuration](#configuration)
*   [Example](#example)
*   [How Enzyme works](#how-enzyme-works)
*   [Full, shallow and string rendering](#full-shallow-and-string-rendering)
*   [Triggering state updates and effects with `act`](#triggering-state-updates-and-effects-with-act)
*   [Differences from Enzyme with React](#differences-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-pact';

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).

---

# Source: https://preactjs.com/guide/v10/web-components

# 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')}>
```

---

# Source: https://preactjs.com/guide/v10/whats-new/#componentdidcatch

# 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)
*   [componentDidCatch](#componentdidcatch)
*   [Hooks](#hooks)
*   [createContext](#createcontext)
*   [CSS Custom Properties](#css-custom-properties)
*   [Compat lives in core](#compat-lives-in-core)
*   [Many compatibility fixes](#many-compatibility-fixes)

---

## 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>
		</div>
	);
}
```

[Run in REPL](/repl?code=ZnVuY3Rpb24gRm9vKCkgewoJcmV0dXJuICgKCQk8PgoJCQk8ZGl2PkE8L2Rpdj4KCQkJPGRpdj5CPC9kaXY%2BCgkJPC8%2BCgkpOwp9)

## 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;
	}
}
```

[Run in REPL](/repl?code=Y2xhc3MgQ2F0Y2hlciBleHRlbmRzIENvbXBvbmVudCB7CglzdGF0ZSA9IHsgZXJyb3JlZDogZmFsc2UgfTsKCgljb21wb25lbnREaWRDYXRjaChlcnJvcikgewoJCXRoaXMuc2V0U3RhdGUoeyBlcnJvcmVkOiB0cnVlIH0pOwoJfQoKCXJlbmRlcihwcm9wcywgc3RhdGUpIHsKCQlpZiAoc3RhdGUuZXJyb3JlZCkgewoJCQlyZXR1cm4gPHA%2BU29tZXRoaW5nIHdlbnQgYmFkbHkgd3Jvbmc8L3A%2BOwoJCX0KCQlyZXR1cm4gcHJvcHMuY2hpbGRyZW47Cgl9Cn0%3D)

## 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>
	);
}
```

[Run in REPL](/repl?code=ZnVuY3Rpb24gQ291bnRlcigpIHsKCWNvbnN0IFt2YWx1ZSwgc2V0VmFsdWVdID0gdXNlU3RhdGUoMCk7Cgljb25zdCBpbmNyZW1lbnQgPSB1c2VDYWxsYmFjaygoKSA9PiBzZXRWYWx1ZSh2YWx1ZSArIDEpLCBbdmFsdWVdKTsKCglyZXR1cm4gKAoJCTxkaXY%2BCgkJCUNvdW50ZXI6IHt2YWx1ZX0KCQkJPGJ1dHRvbiBvbkNsaWNrPXtpbmNyZW1lbnR9PkluY3JlbWVudDwvYnV0dG9uPgoJCTwvZGl2PgoJKTsKfQ%3D%3D)

## 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.

```jsx
// 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 :)