From 665aa17f4c2ce9880b8d0e59c8863ed51b9e8973 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Arthur=20Falc=C3=A3o?= <arthurjvfalcao@gmail.com>
Date: Sun, 28 Nov 2021 17:15:41 +0000
Subject: [PATCH] #503 added useTheme hook documentation (#569)

* feat: add useTheme hook in helper api section

* chore: add tag to the header

* chore: change useContext mention to useTheme on Theming section

* chore: add useContext metion again

Co-authored-by: Ayoub Aabass <ayoub@aabass.net>
Co-authored-by: Evan Jacobs <570070+probablyup@users.noreply.github.com>
---
 sections/advanced/theming.md      | 29 ++++++++++++++++++++++-------
 sections/api/helpers/index.md     |  3 +++
 sections/api/helpers/use-theme.md | 16 ++++++++++++++++
 3 files changed, 41 insertions(+), 7 deletions(-)
 create mode 100644 sections/api/helpers/use-theme.md

diff --git a/sections/advanced/theming.md b/sections/advanced/theming.md
index 6c2b6074e..d316b1bc7 100644
--- a/sections/advanced/theming.md
+++ b/sections/advanced/theming.md
@@ -97,16 +97,16 @@ If you ever need to use the current theme outside styled components (e.g. inside
 the `withTheme` higher order component.
 
 ```jsx
-import { withTheme } from 'styled-components';
+import { withTheme } from 'styled-components'
 
 class MyComponent extends React.Component {
   render() {
-    console.log('Current theme: ', this.props.theme);
+    console.log('Current theme: ', this.props.theme)
     // ...
   }
 }
 
-export default withTheme(MyComponent);
+export default withTheme(MyComponent)
 ```
 
 #### via `useContext` React hook | v4
@@ -114,13 +114,28 @@ export default withTheme(MyComponent);
 You can also use `useContext` to access the current theme outside of styled components when working with React Hooks.
 
 ```jsx
-import { useContext } from 'react';
-import { ThemeContext } from 'styled-components';
+import { useContext } from 'react'
+import { ThemeContext } from 'styled-components'
 
 const MyComponent = () => {
-  const themeContext = useContext(ThemeContext);
+  const themeContext = useContext(ThemeContext)
 
-  console.log('Current theme: ', themeContext);
+  console.log('Current theme: ', themeContext)
+  // ...
+}
+```
+
+#### via `useTheme` custom hook | v5
+
+You can also use `useTheme` to access the current theme outside of styled components when working with React Hooks.
+
+```jsx
+import { useTheme } from 'styled-components'
+
+const MyComponent = () => {
+  const theme = useTheme()
+
+  console.log('Current theme: ', theme)
   // ...
 }
 ```
diff --git a/sections/api/helpers/index.md b/sections/api/helpers/index.md
index 21d503087..36526fd20 100644
--- a/sections/api/helpers/index.md
+++ b/sections/api/helpers/index.md
@@ -5,6 +5,7 @@ import WithTheme from './with-theme.md'
 import CreateGlobalStyle from './create-global-style.md'
 import ThemeConsumer from './theme-consumer.md'
 import StyleSheetManager from './style-sheet-manager.md'
+import UseTheme from './use-theme.md'
 
 ## Helpers
 
@@ -20,4 +21,6 @@ import StyleSheetManager from './style-sheet-manager.md'
 
 <WithTheme />
 
+<UseTheme />
+
 <ThemeConsumer />
diff --git a/sections/api/helpers/use-theme.md b/sections/api/helpers/use-theme.md
new file mode 100644
index 000000000..2d4a78b2f
--- /dev/null
+++ b/sections/api/helpers/use-theme.md
@@ -0,0 +1,16 @@
+### `useTheme` | v5
+
+This is a custom hook to get the current theme from a `ThemeProvider`.
+
+```jsx
+import { useTheme } from 'styled-components'
+
+function MyComponent() {
+  const theme = useTheme()
+  console.log('Current theme: ', theme)
+
+  // ...
+}
+```
+
+> All styled components [automatically receive the theme as a prop](/docs/advanced#theming), so this is only necessary if you wish to access the theme for other reasons.