feat(react): Add IconsProvider (#4268)

aws-amplify · Aug 18, 2023 · f8c5b77 · f8c5b77
1 parent 29775e2
commit f8c5b77
Show file tree

Hide file tree

Showing 76 changed files with 1,509 additions and 333 deletions.
diff --git a/.changeset/few-eggs-sit.md b/.changeset/few-eggs-sit.md
@@ -0,0 +1,34 @@
+---
+"@aws-amplify/ui-react-storage": minor
+"@aws-amplify/ui-react": minor
+---
+
+feat(react): Add IconsProvider to customize icons globally for all Amplify UI components
+
+Components that use icons:
+* Alert
+* Checkbox
+* Expander
+* Field
+* Menu
+* Pagination
+* PasswordField
+* Rating
+* SearchField
+* Select
+* StepperField
+* StorageManager
+
+Wrap your application with the `<IconsProvider>` (or whatever part of your app you want to customize the icons). 
+
+```jsx
+<IconsProvider icons={{
+  alert: {
+    info: <MdInfo />
+  }
+}}>
+  {/* ... */}
+</IconProvider>
+```
+
+Works well with the react-icons package!
diff --git a/docs/__tests__/__snapshots__/sitemap.test.ts.snap b/docs/__tests__/__snapshots__/sitemap.test.ts.snap
@@ -128,6 +128,7 @@ exports[`Sitemap Snapshot 1`] = `
 /react/theming/default-theme/colors, 
 /react/theming/default-theme/sizes, 
 /react/theming/default-theme/typography, 
+/react/theming/icons, 
 /react/theming/responsive, 
 /react/theming/style-props, 
 /react/theming/theme-provider, 

diff --git a/docs/src/data/links.tsx b/docs/src/data/links.tsx
@@ -642,6 +642,11 @@ export const theming: ComponentNavItem[] = [
     platforms: ['react', 'vue', 'angular'],
     tertiary: true,
   },
+  {
+    href: '/theming/icons',
+    label: 'Icons',
+    platforms: ['react'],
+  },
   {
     href: '/theming/theme-provider',
     label: 'ThemeProvider',

diff --git a/docs/src/pages/[platform]/components/alert/examples/AlertIconProviderExample.tsx b/docs/src/pages/[platform]/components/alert/examples/AlertIconProviderExample.tsx
@@ -0,0 +1,33 @@
+import { Alert, Flex, IconsProvider } from '@aws-amplify/ui-react';
+import {
+  FcMediumPriority,
+  FcHighPriority,
+  FcInfo,
+  FcOk,
+  FcMinus,
+} from 'react-icons/fc';
+
+export const AlertIconProviderExample = () => (
+  <IconsProvider
+    icons={{
+      alert: {
+        info: <FcInfo />,
+        success: <FcOk />,
+        error: <FcHighPriority />,
+        warning: <FcMediumPriority />,
+        close: <FcMinus />,
+      },
+    }}
+  >
+    <Flex direction="column">
+      <Alert variation="info" heading="Info">
+        Here is some info
+      </Alert>
+      <Alert variation="success" heading="Success" isDismissible>
+        Hooray!
+      </Alert>
+      <Alert variation="warning" heading="Warning" />
+      <Alert variation="error" heading="Error" />
+    </Flex>
+  </IconsProvider>
+);
diff --git a/docs/src/pages/[platform]/components/alert/examples/index.tsx b/docs/src/pages/[platform]/components/alert/examples/index.tsx
@@ -9,3 +9,4 @@ export { DismissButtonLabelExample } from './DismissButtonLabelExample';
 export { DismissibleAlertExample } from './DismissibleAlertExample';
 export { OnDismissAlertExample } from './OnDismissAlertExample';
 export { RoleOverride } from './RoleOverride';
+export { AlertIconProviderExample } from './AlertIconProviderExample';
diff --git a/docs/src/pages/[platform]/components/alert/react.mdx b/docs/src/pages/[platform]/components/alert/react.mdx
@@ -14,7 +14,8 @@ import {
   AlertStylePropsExample,
   AlertThemeExample,
   DismissButtonLabelExample,
-  RoleOverride
+  RoleOverride,
+  AlertIconProviderExample,
 } from './examples';
 
 <Badge variation="info">Usage note:</Badge> The Alert component has an ARIA `alert` role by default which has some <Link href="#accessibility">accessibility implications</Link>. 
@@ -131,7 +132,7 @@ Use the `onDismiss` prop to pass a function that will run when the Alert is dism
   </ExampleCode>
 </Example>
 
-## CSS Styling
+## Styling
 
 <ThemeExample component="Alert">
   <Example>
@@ -147,6 +148,20 @@ Use the `onDismiss` prop to pass a function that will run when the Alert is dism
   </Example>
 </ThemeExample>
 
+### Icons
+
+<Example>
+  <AlertIconProviderExample />
+
+  <ExampleCode>
+
+  ```tsx file=./examples/AlertIconProviderExample.tsx
+
+  ```
+
+  </ExampleCode>
+</Example>
+
 ### Target classes
 
 <ComponentStyleDisplay componentName="Alert" />

diff --git a/docs/src/pages/[platform]/components/checkboxfield/examples/CheckboxFieldIconExample.tsx b/docs/src/pages/[platform]/components/checkboxfield/examples/CheckboxFieldIconExample.tsx
@@ -0,0 +1,18 @@
+import { CheckboxField, Flex, IconsProvider } from '@aws-amplify/ui-react';
+import { HiMinus, HiCheck } from 'react-icons/hi';
+
+export const CheckboxFieldIconExample = () => (
+  <IconsProvider
+    icons={{
+      checkbox: {
+        checked: <HiCheck />,
+        indeterminate: <HiMinus />,
+      },
+    }}
+  >
+    <Flex direction="column">
+      <CheckboxField name="cat" label="Cat" value="cat" defaultChecked={true} />
+      <CheckboxField name="dog" label="Dog" value="dog" isIndeterminate />
+    </Flex>
+  </IconsProvider>
+);
diff --git a/docs/src/pages/[platform]/components/checkboxfield/examples/index.ts b/docs/src/pages/[platform]/components/checkboxfield/examples/index.ts
@@ -1,5 +1,6 @@
 export { CheckboxFieldControlledExample } from './CheckboxFieldControlledExample';
 export { CheckboxFieldDisabledExample } from './CheckboxFieldDisabledExample';
+export { CheckboxFieldIconExample } from './CheckboxFieldIconExample';
 export { CheckboxFieldIndeterminateExample } from './CheckboxFieldIndeterminateExample';
 export { CheckboxFieldLabelHiddenExample } from './CheckboxFieldLabelHiddenExample';
 export { CheckboxFieldSizesExample } from './CheckboxFieldSizesExample';

diff --git a/docs/src/pages/[platform]/components/checkboxfield/react.mdx b/docs/src/pages/[platform]/components/checkboxfield/react.mdx
@@ -3,6 +3,7 @@ import { CheckboxField } from '@aws-amplify/ui-react';
 import {
   CheckboxFieldControlledExample,
   CheckboxFieldDisabledExample,
+  CheckboxFieldIconExample,
   CheckboxFieldIndeterminateExample,
   CheckboxFieldLabelHiddenExample,
   CheckboxFieldSizesExample,
@@ -172,7 +173,7 @@ Use the `hasError` and `errorMessage` props to mark a CheckboxField as having an
   </Example>
 </StandardHTMLAttributes>
 
-## CSS Styling
+## Styling
 
 <ThemeExample component="CheckboxField" link="checkbox">
   <Example>
@@ -188,6 +189,17 @@ Use the `hasError` and `errorMessage` props to mark a CheckboxField as having an
   </Example>
 </ThemeExample>
 
+### Icons
+
+<Example>
+  <CheckboxFieldIconExample />
+
+  <ExampleCode>
+  ```tsx file=./examples/CheckboxFieldIconExample.tsx
+  ```
+  </ExampleCode>
+</Example>
+
 ### Target classes
 
 <ComponentStyleDisplay componentName="CheckboxField" />

diff --git a/docs/src/pages/[platform]/components/icon/react.mdx b/docs/src/pages/[platform]/components/icon/react.mdx
@@ -54,6 +54,8 @@ import {ICON_NAME} from '@aws-amplify/ui-react';
 import {ICON_NAME} from 'react-icons/md';`
 ```
 
+To customize the default icons used in components like [Alert](alert) and [Rating](rating), you can use the [IconProvider](../theming/icons). 
+
 ## Custom icon
 
 ### Using path data

diff --git a/docs/src/pages/[platform]/components/menu/examples/MenuIconExample.tsx b/docs/src/pages/[platform]/components/menu/examples/MenuIconExample.tsx
@@ -0,0 +1,18 @@
+import { Menu, MenuItem, IconsProvider } from '@aws-amplify/ui-react';
+import { FiMoreHorizontal } from 'react-icons/fi';
+
+export const MenuIconExample = () => (
+  <IconsProvider
+    icons={{
+      menu: {
+        menu: <FiMoreHorizontal />,
+      },
+    }}
+  >
+    <Menu>
+      <MenuItem>Download</MenuItem>
+      <MenuItem>Create a Copy</MenuItem>
+      <MenuItem>Mark as Draft</MenuItem>
+    </Menu>
+  </IconsProvider>
+);
diff --git a/docs/src/pages/[platform]/components/menu/examples/index.ts b/docs/src/pages/[platform]/components/menu/examples/index.ts
@@ -6,3 +6,4 @@ export { MenuItemsExample } from './menuItemsExample';
 export { SizeExample } from './sizeExample';
 export { StylePropsExample } from './stylePropsExample';
 export { MenuThemeExample } from './MenuThemeExample';
+export { MenuIconExample } from './MenuIconExample';
diff --git a/docs/src/pages/[platform]/components/menu/react.mdx b/docs/src/pages/[platform]/components/menu/react.mdx
@@ -11,6 +11,7 @@ import {
   SizeExample,
   StylePropsExample,
   MenuThemeExample,
+  MenuIconExample,
 } from './examples/';
 
 import { Example, ExampleCode } from '@/components/Example';
@@ -29,8 +30,7 @@ Import the `Menu` and `MenuItem` components. Note that the Menu component is ren
   <BasicExample />
   <ExampleCode>
 ```tsx file=./examples/basicExample.tsx
-
-````
+```
   </ExampleCode>
 </Example>
 
@@ -42,9 +42,7 @@ Use the `MenuItem` component to configure Menu options. The example below demons
   <MenuItemsExample />
   <ExampleCode>
 ```tsx file=./examples/menuItemsExample.tsx
-
-````
-
+```
   </ExampleCode>
 </Example>
 
@@ -56,9 +54,7 @@ The default Menu button can be customized by importing the `MenuButton` componen
   <MenuExample />
   <ExampleCode>
 ```tsx file=./examples/menuExample.tsx
-
-````
-
+```
   </ExampleCode>
 </Example>
 
@@ -70,9 +66,7 @@ To control the alignment of the Menu with the Menu button, use the `menuAlign` p
   <MenuAlignExample />
   <ExampleCode>
 ```tsx file=./examples/menuAlignExample.tsx
-
-````
-
+```
   </ExampleCode>
 </Example>
 
@@ -84,9 +78,7 @@ Control the size of the Menu button and items using the `size` prop. Available o
   <SizeExample />
   <ExampleCode>
 ```tsx file=./examples/sizeExample.tsx
-
-````
-
+```
   </ExampleCode>
 </Example>
 
@@ -98,13 +90,12 @@ Create a controlled `Menu` using the `isOpen` and `onOpenChange` props.
   <ControlledExample />
   <ExampleCode>
 ```tsx file=./examples/controlledExample.tsx
-
-````
+```
 
   </ExampleCode>
 </Example>
 
-## CSS Styling
+## Styling
 
 <ThemeExample component="Menu">
   <Example>
@@ -120,6 +111,16 @@ Create a controlled `Menu` using the `isOpen` and `onOpenChange` props.
   </Example>
 </ThemeExample>
 
+### Icons
+
+<Example>
+  <MenuIconExample />
+  <ExampleCode>
+```tsx file=./examples/MenuIconExample.tsx
+```
+  </ExampleCode>
+</Example>
+
 ### Target classes
 
 <ComponentStyleDisplay componentName="Menu" />

diff --git a/docs/src/pages/[platform]/components/pagination/examples/PaginationIconExample.tsx b/docs/src/pages/[platform]/components/pagination/examples/PaginationIconExample.tsx
@@ -0,0 +1,23 @@
+import {
+  Pagination,
+  usePagination,
+  IconsProvider,
+} from '@aws-amplify/ui-react';
+import { FiArrowLeft, FiArrowRight } from 'react-icons/fi';
+
+export const PaginationIconExample = () => {
+  const paginationProps = usePagination({ totalPages: 6 });
+
+  return (
+    <IconsProvider
+      icons={{
+        pagination: {
+          next: <FiArrowRight />,
+          previous: <FiArrowLeft />,
+        },
+      }}
+    >
+      <Pagination {...paginationProps} />
+    </IconsProvider>
+  );
+};
diff --git a/docs/src/pages/[platform]/components/pagination/examples/index.ts b/docs/src/pages/[platform]/components/pagination/examples/index.ts
@@ -5,3 +5,4 @@ export { PaginationStylingExample } from './PaginationStylingExample';
 export { PaginationHasMorePagesExample } from './PaginationHasMorePagesExample';
 export { PaginationSiblingCountExample } from './PaginationSiblingCountExample';
 export { PaginationThemeExample } from './PaginationThemeExample';
+export { PaginationIconExample } from './PaginationIconExample';
diff --git a/docs/src/pages/[platform]/components/pagination/react.mdx b/docs/src/pages/[platform]/components/pagination/react.mdx
@@ -11,6 +11,7 @@ import {
   PaginationSiblingCountExample,
   PaginationStylingExample,
   PaginationThemeExample,
+  PaginationIconExample,
 } from './examples';
 
 ## Demo
@@ -108,7 +109,7 @@ By default, the root node of the Pagination component is a `<nav>` element. Elem
   </ExampleCode>
 </Example>
 
-## CSS styling
+## Styling
 
 <ThemeExample component="Pagination">
   <Example>
@@ -124,6 +125,16 @@ By default, the root node of the Pagination component is a `<nav>` element. Elem
   </Example>
 </ThemeExample>
 
+### Icons
+
+<Example>
+  <PaginationIconExample />
+
+  <ExampleCode>
+  ```tsx file=./examples/PaginationIconExample.tsx
+  ```
+  </ExampleCode>
+</Example>
 
 ### Target classes