From 4c29b69558c401648f9e104dbd0dc7ab83e2fe51 Mon Sep 17 00:00:00 2001
From: Brian Vaughn <bvaughn@fb.com>
Date: Tue, 15 Jan 2019 13:04:49 -0800
Subject: [PATCH] Add docs for useDebugValue

---
 content/docs/hooks-reference.md | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/content/docs/hooks-reference.md b/content/docs/hooks-reference.md
index 9d4f3930..0eb348f4 100644
--- a/content/docs/hooks-reference.md
+++ b/content/docs/hooks-reference.md
@@ -23,6 +23,7 @@ If you're new to Hooks, you might want to check out [the overview](/docs/hooks-o
   - [`useRef`](#useref)
   - [`useImperativeMethods`](#useimperativemethods)
   - [`useLayoutEffect`](#uselayouteffect)
+  - [`useDebugValue`](#usedebugvalue)
 
 ## Basic Hooks
 
@@ -353,3 +354,31 @@ Prefer the standard `useEffect` when possible to avoid blocking visual updates.
 > Tip
 >
 > If you're migrating code from a class component, `useLayoutEffect` fires in the same phase as `componentDidMount` and `componentDidUpdate`, so if you're unsure of which effect Hook to use, it's probably the least risky.
+
+### `useDebugValue`
+
+```js
+useDebugValue(value)
+```
+
+`useDebugValue` can be used to provide a label for the React DevTools to display beside of a custom hook.
+
+For example, consider the `useFriendStatus` custom hook described in ["Building Your Own Hooks"](/docs/hooks-custom.html):
+
+```js{6-8}
+function useFriendStatus(friendID) {
+  const [isOnline, setIsOnline] = useState(null);
+
+  // ...
+
+  // Show a label in DevTools beside of this hook
+  // e.g. "FriendStatus: Online"
+  useDebugValue(isOnline ? 'Online' : 'Offline');
+
+  return isOnline;
+}
+```
+
+> Tip
+>
+> We don't recommend adding debug values to every custom hook. It's most valuable for custom hooks that are part of shared libraries.
\ No newline at end of file