Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Remove useMutationEffect docs #1440

Merged
merged 1 commit into from
Nov 28, 2018
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions content/docs/hooks-faq.md
Original file line number Diff line number Diff line change
Expand Up @@ -443,7 +443,7 @@ function Form() {
const [text, updateText] = useState('');
const textRef = useRef();

useMutationEffect(() => {
useLayoutEffect(() => {
textRef.current = text; // Write it to the ref
});

Expand Down Expand Up @@ -484,7 +484,7 @@ function useEventCallback(fn, dependencies) {
throw new Error('Cannot call an event handler while rendering.');
});

useMutationEffect(() => {
useLayoutEffect(() => {
ref.current = fn;
}, [fn, ...dependencies]);

Expand Down
15 changes: 2 additions & 13 deletions content/docs/hooks-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,6 @@ If you're new to Hooks, you might want to check out [the overview](/docs/hooks-o
- [`useMemo`](#usememo)
- [`useRef`](#useref)
- [`useImperativeMethods`](#useimperativemethods)
- [`useMutationEffect`](#usemutationeffect)
- [`useLayoutEffect`](#uselayouteffect)

## Basic Hooks
Expand Down Expand Up @@ -123,7 +122,7 @@ The clean-up function runs before the component is removed from the UI to preven

Unlike `componentDidMount` and `componentDidUpdate`, the function passed to `useEffect` fires **after** layout and paint, during a deferred event. This makes it suitable for the many common side effects, like setting up subscriptions and event handlers, because most types of work shouldn't block the browser from updating the screen.

However, not all effects can be deferred. For example, a DOM mutation that is visible to the user must fire synchronously before the next paint so that the user does not perceive a visual inconsistency. (The distinction is conceptually similar to passive versus active event listeners.) For these types of effects, React provides two additional Hooks: [`useMutationEffect`](#usemutationeffect) and [`useLayoutEffect`](#uselayouteffect). These Hooks have the same signature as `useEffect`, and only differ in when they are fired.
However, not all effects can be deferred. For example, a DOM mutation that is visible to the user must fire synchronously before the next paint so that the user does not perceive a visual inconsistency. (The distinction is conceptually similar to passive versus active event listeners.) For these types of effects, React provides one additional Hook called [`useLayoutEffect`](#uselayouteffect). It has the same signature as `useEffect`, and only differs in when it is fired.

Although `useEffect` is deferred until after the browser has painted, it's guaranteed to fire before any new renders. React will always flush a previous render's effects before starting a new update.

Expand Down Expand Up @@ -345,19 +344,9 @@ FancyInput = forwardRef(FancyInput);

In this example, a parent component that renders `<FancyInput ref={fancyInputRef} />` would be able to call `fancyInputRef.current.focus()`.

### `useMutationEffect`

The signature is identical to `useEffect`, but it fires synchronously during the same phase that React performs its DOM mutations, before sibling components have been updated. Use this to perform custom DOM mutations.

Prefer the standard `useEffect` when possible to avoid blocking visual updates.

>Note
>
>Avoid reading from the DOM in `useMutationEffect`. If you do, you can cause performance problems by introducing [layout thrash](https://developers.google.com/web/fundamentals/performance/rendering/avoid-large-complex-layouts-and-layout-thrashing). When reading computed styles or layout information, `useLayoutEffect` is more appropriate.

### `useLayoutEffect`

The signature is identical to `useEffect`, but it fires synchronously *after* all DOM mutations. Use this to read layout from the DOM and synchronously re-render. Updates scheduled inside `useLayoutEffect` will be flushed synchronously, before the browser has a chance to paint.
The signature is identical to `useEffect`, but it fires synchronously after all DOM mutations. Use this to read layout from the DOM and synchronously re-render. Updates scheduled inside `useLayoutEffect` will be flushed synchronously, before the browser has a chance to paint.

Prefer the standard `useEffect` when possible to avoid blocking visual updates.

Expand Down