diff --git a/docs/public/example-auth-routes.png b/docs/public/example-auth-routes.png
new file mode 100644
index 00000000000..7356218e52a
Binary files /dev/null and b/docs/public/example-auth-routes.png differ
diff --git a/docs/src/components/Layout/Header.tsx b/docs/src/components/Layout/Header.tsx
index 026fb2cf3fa..77868253678 100644
--- a/docs/src/components/Layout/Header.tsx
+++ b/docs/src/components/Layout/Header.tsx
@@ -67,6 +67,9 @@ const Nav = (props) => (
Theming
+
+ Guides
+
Amplify docs
diff --git a/docs/src/components/Layout/SecondaryNav.tsx b/docs/src/components/Layout/SecondaryNav.tsx
index d14db03ca9f..cc7c8f3d757 100644
--- a/docs/src/components/Layout/SecondaryNav.tsx
+++ b/docs/src/components/Layout/SecondaryNav.tsx
@@ -107,6 +107,19 @@ export const SecondaryNav = (props) => {
);
}
+ if (section === 'guides') {
+ return (
+ <>
+
+ Guides
+
+
+ Protected Routes
+
+
+ );
+ }
+
if (section === 'getting-started') {
return (
<>
diff --git a/docs/src/data/meta.ts b/docs/src/data/meta.ts
index c445e70a21c..9514a35b982 100644
--- a/docs/src/data/meta.ts
+++ b/docs/src/data/meta.ts
@@ -223,6 +223,15 @@ export const META_INFO: MetaInfo = {
description:
'A Theme is a structured collection of design decisions that change the appearance of a UI library. An Amplify UI theme is a structured object of design tokens, breakpoints, and overrides. - Amplify UI',
},
+ '/guides': {
+ title: 'Guides',
+ description:
+ 'Amplify guides are meant to give you a more in-depth understanding of how to use the Amplify CLI, libraries, and hosting to build out common functionality, end-to-end solutions, and frequently asked for workflows.',
+ },
+ '/guides/auth-protected': {
+ title: 'Guides',
+ description: 'How to protect routes with Amplify Authenticator.',
+ },
'/theming/default-theme': {
title: 'Theming - Default Theme',
description:
diff --git a/docs/src/pages/guides/auth-protected/auth-protected.angular.mdx b/docs/src/pages/guides/auth-protected/auth-protected.angular.mdx
new file mode 100644
index 00000000000..4dc6b8bca63
--- /dev/null
+++ b/docs/src/pages/guides/auth-protected/auth-protected.angular.mdx
@@ -0,0 +1 @@
+## Coming Soon
diff --git a/docs/src/pages/guides/auth-protected/auth-protected.flutter.mdx b/docs/src/pages/guides/auth-protected/auth-protected.flutter.mdx
new file mode 100644
index 00000000000..4dc6b8bca63
--- /dev/null
+++ b/docs/src/pages/guides/auth-protected/auth-protected.flutter.mdx
@@ -0,0 +1 @@
+## Coming Soon
diff --git a/docs/src/pages/guides/auth-protected/auth-protected.react.mdx b/docs/src/pages/guides/auth-protected/auth-protected.react.mdx
new file mode 100644
index 00000000000..29cb3dc785f
--- /dev/null
+++ b/docs/src/pages/guides/auth-protected/auth-protected.react.mdx
@@ -0,0 +1,466 @@
+import { Image } from '@aws-amplify/ui-react';
+import { ExampleCode } from '@/components/Example';
+
+The [Amplify UI Authenticator](/components/authenticator) component allows you to quickly scaffold out an end-to-end authentication flow, in just a few lines of code.
+
+Typically, this can be accomplished by wrapping the entire application in the [withAuthenticator](components/authenticator?platform=react#quick-start) higher-order component. This forces the entire application behind a login page.
+
+Let's imagine you needed a web application where the login page was in its own route, and that you needed a handful of selected routes to only be accessed by logged in users.
+
+This guide demonstrates that scenario while using the [Amplify UI Authenticator](/components/authenticator) and the [Amplify CLI](https://docs.amplify.aws/cli/).
+
+> If you'd like to follow along, please use this example [Github repo](https://github.com/ErikCH/protected-route-amplify-react). Additionally, you can watch this [video](https://youtu.be/6f635LVtwgk) that walks through this process, and includes a bonus section on how to create a lambda function with a custom authorizer.
+
+_Example Screenshot of App_
+
+
+
+### Setup
+
+To get started we'll need to create a new React application, by following these steps:
+
+
+```bash
+npx create-react-app new-auth-app
+cd new-auth-app
+
+````
+
+
+
+Next, install the Amplify libraries and React Router.
+
+
+```bash
+npm i @aws-amplify/ui-react aws-amplify react-router-dom@6
+````
+
+
+
+To add authentication to your application we'll need to install the Amplify CLI. This tool gives us a command line utility to add AWS services.
+
+
+```bash
+npm i @aws-amplify/cli -g
+```
+
+
+
+After this, run the `amplify init` command. This will setup your application so it can communicate with your AWS account.
+
+
+```bash
+amplify init
+````
+
+
+
+Next, add authentication, and follow the prompts below:
+
+
+```bash
+amplify add auth
+
+? Do you want to use the default authentication and security configuration? Default configuration
+? How do you want users to be able to sign in? Email
+? Do you want to configure advanced settings? No, I am done.
+
+````
+
+
+
+Finally, run the `push` command to deploy your new AWS backend.
+
+
+```bash
+amplify push
+````
+
+
+
+Last thing you should do is copy and paste the following CSS into your `App.css` file:
+
+
+
+```css
+/* App.css */
+#root {
+ text-align: center;
+ margin: 1.2rem;
+}
+
+nav {
+ display: flex;
+ justify-content: center;
+ gap: 2rem;
+ margin-bottom: 2rem;
+}
+
+.auth-wrapper {
+ display: flex;
+ justify-content: center;
+ margin-top: 2rem;
+}
+```
+
+
+
+Feel free to modify it, this will help with the look and feel of your example application.
+
+You should now be ready to dive into the React code.
+
+## Setting up the Authenticator
+
+One of the most important parts of your application is adding and configuring the Authenticator.
+
+Let's begin by opening up the `index.js` file and adding the following configuration:
+
+
+```js
+// index.js
+...
+import awsExports from "./aws-exports";
+import "./index.css";
+
+Amplify.configure(awsExports);
+...
+
+````
+
+
+
+This imports the newly created `aws-exports` file into your app and configures it with Amplify.
+
+Next, create a new `components` folder in the root of your application. In here create a new `Login` component.
+
+This component will display the `Authenticator` and allow you to create new users and log in. If you like to add additional configuration you can look at the [configuration documentation](/components/authenticator).
+
+In addition, after a user logs in, it will redirected them to the last place they navigated to. This is a very helpful pattern when working with protected routes. If you'd like more information on this pattern please see the [React Router Auth documentation](https://reactrouter.com/docs/en/v6/examples/auth).
+
+
+
+```jsx
+// components/Login.js
+import { useEffect } from "react";
+
+import { Authenticator, useAuthenticator, View } from '@aws-amplify/ui-react';
+import '@aws-amplify/ui-react/styles.css';
+
+import { useNavigate, useLocation } from 'react-router';
+
+export function Login() {
+ const { route } = useAuthenticator((context) => [context.route]);
+ const location = useLocation();
+ const navigate = useNavigate();
+ let from = location.state?.from?.pathname || '/';
+ useEffect(() => {
+ if (route === 'authenticated') {
+ navigate(from, { replace: true });
+ }
+ }, [route, navigate, from]);
+ return (
+
+
+
+ );
+}
+```
+
+
+Let's take a look at this line in more detail:
+
+
+```js
+const { route } = useAuthenticator((context) => [context.route]);
+````
+
+
+
+The [useAuthenticator](/components/authenticator#useauthenticator-hook) hook is used to access, modify, and update the Authenticator's auth state. In this example we destructure `useAuthenticator` and receive the `route`. The `route` can be used to tell if a route is `authenticated` or not. The `route` can also be set to `signIn`,`signOut`, and even `idle` or `setup` depending on where the user is during the authentication flow.
+
+> You may have noticed that we passed into the `useAuthenticator` a context callback function: `(context) => [context.route]` This is very important as it will help prevent unneccessary re-renders of the application. Excluding it may also cause errors!
+
+Let's take a look at the `useEffect` below:
+
+
+```js
+useEffect(() => {
+ if (route === 'authenticated') {
+ navigate(from, { replace: true });
+ }
+}, [route, navigate, from]);
+```
+
+
+When the `route` changes to `authenticated` the `useEffect` will trigger and the user will be navigated to the previous location.
+
+Alternatively, instead of using `route` this can also be accomplished using `Auth.currentAuthenticatedUser()`. This promise from the `aws-amplify` [library](https://docs.amplify.aws/lib/auth/manageusers/q/platform/js/) will return the `user` information back. If the user isn't logged in the promise will reject.
+
+## Adding in a RequireAuth component
+
+Let's take a look at `RequireAuth` next. This component will be used to gate whether a route can be accessed or not. Routes that are **NOT** authenticated will be redirected back to `/login`. State will also be preserved.
+
+If the customer is logged in, the `route` will be set to `authenticated`, and the user can continue on.
+
+Create a new file called `RequireAuth.js` and add the code below:
+
+
+```jsx
+// RequireAuth.js
+import { useLocation, Navigate } from 'react-router-dom';
+import { useAuthenticator } from '@aws-amplify/ui-react';
+
+export function RequireAuth({ children }) {
+ const location = useLocation();
+ const { route } = useAuthenticator((context) => [context.route]);
+ if (route !== 'authenticated') {
+ return ;
+ }
+ return children;
+}
+```
+
+
+> If you're logged in and refresh the browser, the `route` may temporarily be set to `idle` or `setup` while it loads. That will cause a redirection back to the `/login` page, which in turn will redirect back to the protected route. The user will not notice anything, and the protected route will be displayed. However, if you like to have more control of this process you can use `Auth.currentAuthenticatedUser()` instead.
+
+We'll need to use this component later.
+
+### Add the other components
+
+Before we can setup the router, let's setup the rest of the components.
+
+First, let's create the `Protected`, `ProtectSecond`, and `Home` components in the `components` folder.
+
+The `Home` component will display a simple message for users on the root index route.
+
+
+
+```jsx
+// components/Home.js
+import { Heading } from '@aws-amplify/ui-react';
+export function Home() {
+ return (
+
+ Please use the buttons at the top to test out protected routes!
+
+ );
+}
+```
+
+
+
+Next up are the two protected routes. They will show a message on the page if the user is `authenticated`. If not it will
+show `Loading`.
+
+
+
+```jsx
+// components/Protected.js
+import { useAuthenticator, Heading } from '@aws-amplify/ui-react';
+export function Protected() {
+ const { route } = useAuthenticator((context) => [context.route]);
+
+ const message =
+ route === 'authenticated' ? 'FIRST PROTECTED ROUTE!' : 'Loading...';
+ return {message};
+}
+```
+
+
+
+Same with the second protected component.
+
+
+
+```jsx
+// components/ProtectSecond.js
+import { useAuthenticator, Heading } from '@aws-amplify/ui-react';
+export function ProtectedSecond() {
+ const { route } = useAuthenticator((context) => [context.route]);
+
+ const message =
+ route === 'authenticated' ? 'SECOND PROTECTED ROUTE!' : 'Loading...';
+ return {message};
+}
+```
+
+
+
+Lastly, we'll create a `Layout` that will surround the whole application and give us a nice menu bar at the top.
+
+
+
+```jsx
+// components/Layout.js
+import React from 'react';
+import { Outlet, useNavigate } from 'react-router-dom';
+import { useAuthenticator, Button, Heading, View } from '@aws-amplify/ui-react';
+
+export function Layout() {
+ const { route, signOut } = useAuthenticator((context) => [
+ context.route,
+ context.signOut,
+ ]);
+ const navigate = useNavigate();
+
+ function logOut() {
+ signOut();
+ navigate('/login');
+ }
+ return (
+ <>
+
+ Example Auth Routes App
+
+ {route === 'authenticated' ? 'You are logged in!' : 'Please Login!'}
+
+
+
+
+ );
+}
+```
+
+
+
+You'll notice that we are using the `route` to check if the user is `authenticated` again. This is helpful because we can use it to show a different message for users who are logged in versus those who are not.
+
+When a user logs out, we'll navigate them back to the `/login` page.
+
+## Adding the router and protecting routes
+
+At this point we are ready to add in the router and start protecting routes.
+
+Inside the `App.js` file delete all the code. Update the file as seen below:
+
+
+
+```jsx
+//App.js
+import { Authenticator } from '@aws-amplify/ui-react';
+
+import { Protected } from './components/Protected';
+import { RequireAuth } from './RequireAuth';
+import { Login } from './components/Login';
+import { ProtectedSecond } from './components/ProtectSecond';
+import { Home } from './components/Home';
+import { Layout } from './components/Layout';
+
+import { BrowserRouter, Routes, Route } from 'react-router-dom';
+
+import './App.css';
+
+function MyRoutes() {
+ return (
+
+
+ }>
+ } />
+
+
+
+ }
+ />
+
+
+
+ }
+ />
+ } />
+
+
+
+ );
+}
+
+function App() {
+ return (
+
+
+
+ );
+}
+
+export default App;
+```
+
+
+
+Let's break this down, since we have a multiple route application, we must surround our main app with the `Authentication.Provider`.
+
+
+```jsx
+function App() {
+ return (
+
+
+
+ );
+}
+````
+
+
+
+This will assure us that we can use the `useAuthenticator` hook anywhere in your application without issues.
+
+Another important factor is protecting routes. Since we have created the `RequireAuth` component we can now use it to surround any route component that we want protected, as seen below:
+
+
+ ```jsx
+
+
+
+ }
+ />
+ ```
+
+
+That's all we have to do. Now this route will be protected, and if anyone tries to navigate to it, without being logged in, they'll be redirected to the `/login` page.
+
+## Try it out!
+
+Feel free to run the application and try it out!
+
+
+```bash
+npm start
+```
+
+
+
+Try clicking on a protected route and getting redirected to the `/login` page. After you log in, you'll be redirected to the previous protected route!
+
+## Conclusion
+
+Congratulations! You've now setup your very own protected route React application using the AWS Amplify UI libraries!
+
+If you find any problems with this tutorial, please open an issue on [Github](https://github.com/aws-amplify/amplify-ui/issues/new/choose).
diff --git a/docs/src/pages/guides/auth-protected/auth-protected.vue.mdx b/docs/src/pages/guides/auth-protected/auth-protected.vue.mdx
new file mode 100644
index 00000000000..4dc6b8bca63
--- /dev/null
+++ b/docs/src/pages/guides/auth-protected/auth-protected.vue.mdx
@@ -0,0 +1 @@
+## Coming Soon
diff --git a/docs/src/pages/guides/auth-protected/index.page.mdx b/docs/src/pages/guides/auth-protected/index.page.mdx
new file mode 100644
index 00000000000..f0dd1505f9b
--- /dev/null
+++ b/docs/src/pages/guides/auth-protected/index.page.mdx
@@ -0,0 +1,9 @@
+---
+title: How to create a React application with protected routes using the Authenticator component
+---
+
+import { Fragment } from '@/components/Fragment';
+
+
+ {({ platform }) => import(`./auth-protected.${platform}.mdx`)}
+
diff --git a/docs/src/pages/guides/guide.web.mdx b/docs/src/pages/guides/guide.web.mdx
new file mode 100644
index 00000000000..2ad9cfb4cc8
--- /dev/null
+++ b/docs/src/pages/guides/guide.web.mdx
@@ -0,0 +1,15 @@
+## Guides
+
+Amplify guides are meant to give you a more in-depth understanding of how to use the Amplify UI components and theming to build out common functionality, end-to-end solutions, and frequently asked for workflows.
+
+## Overview
+
+Guides are organized by topic, but some guides may overlap multiple topics (i.e. Authentication & Theming) to demonstrate how to integrate multiple services together.
+
+Guides may combine the CLI and libraries together in a single tutorial. This is done to provide an end-to-end solution using both the service creation and configuration as well as connecting to and interacting with the service from a client-side application.
+
+## Contributing
+
+If there is a guide or idea that you would like to see implemented that is not listed, open a [GitHub Issue](https://github.com/aws-amplify/amplify-ui/issues/new/choose) with the details of the use case and it will be reviewed by our team and considered.
+
+If you have an idea for a guide that you'd like to write yourself, submit a pull request. However, make sure to submit an issue with the details of your idea before you submit your PR, so you can receive guidance and feedback.
diff --git a/docs/src/pages/guides/index.page.mdx b/docs/src/pages/guides/index.page.mdx
new file mode 100644
index 00000000000..1aad6061f4d
--- /dev/null
+++ b/docs/src/pages/guides/index.page.mdx
@@ -0,0 +1,9 @@
+---
+title: Overview
+---
+
+import { Fragment } from '@/components/Fragment';
+
+
+ {({ platform }) => import(`./guide.${platform}.mdx`)}
+