> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/preactjs/preact/llms.txt
> Use this file to discover all available pages before exploring further.
# React vs Preact Differences
> Key differences between React and Preact when using the compat layer
## Overview
While `preact/compat` provides excellent React compatibility, there are some differences in behavior and implementation details. Most applications won't encounter these, but it's important to be aware of them.
In most cases, preact/compat provides 100% compatibility with React for standard usage patterns. Differences typically only matter for edge cases or advanced usage.
## Core Differences
### Synthetic Events
Preact uses native browser events instead of React's synthetic event system.
**React:**
```jsx theme={null}
function handleClick(e) {
// e is a SyntheticEvent wrapper
e.persist(); // Needed to access event async
setTimeout(() => {
console.log(e.type); // Works in React
}, 100);
}
```
**Preact:**
```jsx theme={null}
function handleClick(e) {
// e is a native Event
// e.persist() is a no-op (see compat/src/render.js:100)
setTimeout(() => {
console.log(e.type); // Works in Preact
}, 100);
}
```
The compat layer adds a no-op `persist()` method to events at [compat/src/render.js:100](https://github.com/preactjs/preact/blob/main/compat/src/render.js:100) for compatibility, but it's not needed since Preact uses native events.
**Implications:**
* Native events are not pooled (no need for `e.persist()`)
* Event properties can be accessed asynchronously without issues
* Slightly better performance due to no synthetic event overhead
### Event Naming
Preact automatically normalizes React event names to their browser equivalents:
```jsx theme={null}
// These are automatically converted by the compat layer:
// → oninput (for text inputs)
// → ondblclick
// → onfocusin
// → onfocusout
```
The conversion logic is in [compat/src/render.js:168](https://github.com/preactjs/preact/blob/main/compat/src/render.js:168).
For ``, ``, and ``, `onChange` behaves exactly like React's onChange, not as oninput.
### className vs class
Preact supports both `class` and `className` props:
```jsx theme={null}
// Both work in Preact:
```
The compat layer ensures both are supported (see [compat/src/render.js:227](https://github.com/preactjs/preact/blob/main/compat/src/render.js:227)).
## Lifecycle Methods
### Unsafe Lifecycle Methods
Preact supports both prefixed and unprefixed unsafe lifecycle methods through property getters/setters:
```jsx theme={null}
class MyComponent extends Component {
// Both of these work:
componentWillMount() { }
UNSAFE_componentWillMount() { }
componentWillReceiveProps(nextProps) { }
UNSAFE_componentWillReceiveProps(nextProps) { }
componentWillUpdate(nextProps, nextState) { }
UNSAFE_componentWillUpdate(nextProps, nextState) { }
}
```
The aliasing is implemented at [compat/src/render.js:49](https://github.com/preactjs/preact/blob/main/compat/src/render.js:49).
While these lifecycle methods are supported, they're deprecated in React and should be avoided in new code.
## Concurrent Features
### Transitions and Deferred Values
`useTransition` and `useDeferredValue` are implemented but don't provide true concurrent rendering:
```jsx theme={null}
import { useTransition, useDeferredValue } from 'react';
function MyComponent() {
const [isPending, startTransition] = useTransition();
// isPending is always false
// startTransition executes immediately
const deferredValue = useDeferredValue(value);
// Returns the value immediately (no deferral)
}
```
Implementation details:
* `startTransition` is a passthrough function at [compat/src/hooks.js:52](https://github.com/preactjs/preact/blob/main/compat/src/hooks.js:52)
* `useDeferredValue` returns the value unchanged at [compat/src/hooks.js:56](https://github.com/preactjs/preact/blob/main/compat/src/hooks.js:56)
* `useTransition` always returns `[false, startTransition]` at [compat/src/hooks.js:60](https://github.com/preactjs/preact/blob/main/compat/src/hooks.js:60)
Code that relies on actual concurrent rendering behavior won't work the same way in Preact. These hooks are provided for API compatibility only.
### flushSync
`flushSync` is implemented as a passthrough in Preact:
```jsx theme={null}
import { flushSync } from 'react-dom';
// In React: Forces synchronous render
// In Preact: Just executes the callback (compat/src/index.js:132)
flushSync(() => {
setState(newValue);
});
```
### Suspense and Lazy Loading
Suspense and lazy loading are fully supported:
```jsx theme={null}
import { lazy, Suspense } from 'react';
const LazyComponent = lazy(() => import('./Component'));
function App() {
return (
Loading...}>
);
}
```
The implementation at [compat/src/suspense.js:218](https://github.com/preactjs/preact/blob/main/compat/src/suspense.js:218) provides full Suspense support including:
* Error boundaries for promise rejection
* Proper fallback rendering
* Support for nested Suspense boundaries
## Rendering Differences
### Render Return Value
Preact's render returns the component instance, matching React's behavior:
```jsx theme={null}
import { render } from 'react-dom';
const instance = render(, container);
// instance is the root component (or null for functional components)
```
This is ensured by the compat layer at [compat/src/render.js:86](https://github.com/preactjs/preact/blob/main/compat/src/render.js:86).
### Container Clearing
React clears container content on first render:
```jsx theme={null}
const container = document.getElementById('root');
container.innerHTML = '
This will be cleared
';
// First render clears the container
render(, container);
```
Preact/compat implements the same behavior at [compat/src/render.js:79](https://github.com/preactjs/preact/blob/main/compat/src/render.js:79).
### Hydration
Hydration works similarly to React:
```jsx theme={null}
import { hydrateRoot } from 'react-dom/client';
// or legacy:
import { hydrate } from 'react-dom';
hydrate(, container);
```
## Props and Attributes
### defaultValue and value
The compat layer handles `defaultValue` as a fallback for `value`:
```jsx theme={null}
// If value is null/undefined, defaultValue is used
// Renders with value="fallback"
```
Implementation: [compat/src/render.js:152](https://github.com/preactjs/preact/blob/main/compat/src/render.js:152)
### SVG Attributes
Preact automatically converts camelCase SVG attributes to kebab-case:
```jsx theme={null}
// These are converted automatically:
```
The conversion regex is at [compat/src/render.js:32](https://github.com/preactjs/preact/blob/main/compat/src/render.js:32).
### Style Object
Numeric style values automatically get 'px' appended (except for unitless properties):
```jsx theme={null}
```
Implementation: [compat/src/render.js:148](https://github.com/preactjs/preact/blob/main/compat/src/render.js:148)
### Boolean Attributes
The download attribute with `true` value becomes an empty string:
```jsx theme={null}
// In React and Preact/compat:
// Renders as:
```
This prevents the file from being named "true" ([compat/src/render.js:159](https://github.com/preactjs/preact/blob/main/compat/src/render.js:159)).
## Component Features
### PureComponent
PureComponent performs shallow comparison of props and state:
```jsx theme={null}
import { PureComponent } from 'react';
class MyComponent extends PureComponent {
render() {
// Only re-renders if props or state shallowly differ
return