From 2a215944f29558800a917eac2f3bbf29ce7b3ca7 Mon Sep 17 00:00:00 2001 From: "Mauro E. Bender" Date: Thu, 29 Sep 2022 12:15:40 +0200 Subject: [PATCH] Improve Icon component docs --- docs/docs/components/icon.md | 211 ++++++++++-------- .../components/ExampleCustomIcon/index.tsx | 4 +- 2 files changed, 122 insertions(+), 93 deletions(-) diff --git a/docs/docs/components/icon.md b/docs/docs/components/icon.md index 22e0cc3..c2e42ec 100644 --- a/docs/docs/components/icon.md +++ b/docs/docs/components/icon.md @@ -1,5 +1,6 @@ import { Icon, HStack } from '@amalgama/react-native-ui-kit' import EvilIcons from 'react-native-vector-icons/EvilIcons'; +import FontAwesomeIcon from 'react-native-vector-icons/FontAwesome'; import Ionicons from 'react-native-vector-icons/Ionicons'; import CodePreview from '@site/src/components/CodePreview'; import ExampleCustomIcon from '@site/src/components/ExampleCustomIcon'; @@ -19,7 +20,7 @@ import { Icon } from '@amalgama/react-native-ui-kit'; @@ -28,120 +29,54 @@ import { Icon } from '@amalgama/react-native-ui-kit'; ```jsx ``` -## Props - -### as -The icon library Component to be used as the base icon. The Component should comply to the following props interface: - -```ts -interface AsComponentProps { - name: string, - size?: number | undefined, - color?: ColorValue | number | undefined -} -``` - -Where: -- __name__: The name of the icon for that Icon family. -- __size__: The size of the icon in pixels. -- __color__: The color of the icon. - -Here is an example using the `EvilIcons` family from the `react-native-vector-icons` library: - - - - - -```tsx -import EvilIcons from 'react-native-vector-icons/EvilIcons'; - - -``` +## Use it with react-native-vector-icons -### name -The name of the icon in the package select for the `as` prop. This prop will be passed as the `name` prop to the `as` icon component. +You can use any of the icons libraries provided by [react-native-vector-icons](https://github.com/oblador/react-native-vector-icons) with the `Icon` component. In order to achieve this you have to first follow the step to [install the library in your project](https://github.com/oblador/react-native-vector-icons#installation) and then choose a icon library and use it as follows: - + ```tsx -import Ionicons from 'react-native-vector-icons/Ionicons'; - - -``` - - -### size +import FontAwesomeIcon from 'react-native-vector-icons/FontAwesome'; -The size of the Icon. The available sizes are resolved using the theme configuration for the Icon component: - -```js -{ - components: { - Icon: { - sizes: { - 'xs': 14, - 'sm': 18, - 'md': 24, - 'lg': 34, - 'xl': 48, - '2xl': 72, - '3xl': 96 - } - } - } -} + ``` - - - - -```tsx - -``` - -### color - -The color of the Icon. The resulting color is resolved using the current theme's configuration and passed to the `as` component. +:::info +`react-native-vector-icons` also support web platform, please refer to the [web installation guide](https://github.com/oblador/react-native-vector-icons#web-with-webpack) for more information about using it in web. +::: - - - +## Use your own custom SVG icons -```tsx - -``` - -## How to use custom svg icons For using your own svg icons you have two options: -1. Add your icon to the `UIKitIcon` component by a Merge Request. +### 1. Create your own custom icons library -2. Use the `as` prop to pass your own component. You can use the inline way (not recommended) where you pass a function that returns your component and doesn't use the `name` prop. But it's recommended you create a custom component that uses the `name` prop to choose the desired icon from your icon's pool. +You can create your own component that functions as a proxy between the `Icon` component and your custom SVG icons. This component must support the props required to be used in the `as` prop: -If you are using `typescript` you may encounter some problems with the svg props types. Check the troubleshooting section for more information. +- __name__: The name of the icon that you can use to identify which custom SVG icon to use. +- __size__: The size of the icon in pixels. +- __color__: The color of the icon as a CSS color value. + +#### Example -### Recommended way - -This is a basic example of how we do it in the `UIKitIcon` component. You can use this as a base for your custom component. - ```tsx import { Path, Svg } from 'react-native-svg'; -const AlertCircle = ({size, color, ...props}) => ( +// This is your custom icon using the react-native-svg library. +const AlertCircle = ( {size, color, ...props} ) => ( ( fill={color} /> -) +); + export default AlertCircle; ``` @@ -166,6 +102,8 @@ ICON_MAP = { 'alert-circle': AlertCircle } +// This is your custom icon lib component that uses the correct svg icon +// depending on the name prop. const MyIconLib = ({name, ...props}) => { const Icon = ICON_MAP[name]; return @@ -179,21 +117,112 @@ export default MyIconLib; import { Icon } from '@amalgama/react-native-ui-kit'; import MyIconLib from './MyIconLib'; - - +// Use it as any other icon library + ``` -### Inline way +### 2. Pass your custom icon directly to the as property + +You can you pass your custom component directly to the `as` prop. Using this form the `name` proprty is not use it since you're always returning the same icon not matter the value of that property. If you have multiple custom we __strongly__ recommend using the first option instead of this one. + ```tsx import { Path, Svg } from 'react-native-svg'; import AlertCircle from './AlertCircle'; - +``` +:::info +If you are using `typescript` you may encounter some problems with the svg props types. Check the troubleshooting section for more information. +::: + + +## Props + +### as +The icon library Component to be used as the base icon. The Component should comply to the following props interface: + +```ts +interface AsComponentProps { + name: string, + size?: number | undefined, + color?: ColorValue | number | undefined +} +``` + +Where: +- __name__: The name of the icon for that Icon family. +- __size__: The size of the icon in pixels. +- __color__: The color of the icon. + +Here is an example using the `EvilIcons` family from the `react-native-vector-icons` library: + + + + + +```tsx +import EvilIcons from 'react-native-vector-icons/EvilIcons'; + + +``` + +### name +The name of the icon in the package select for the `as` prop. This prop will be passed as the `name` prop to the `as` icon component. + + + + +```tsx +import Ionicons from 'react-native-vector-icons/Ionicons'; + + +``` + +### color + +The color of the Icon. The resulting color is resolved using the current theme's configuration and passed to the `as` component. + + + + + +```tsx + +``` + +### size + +The size of the Icon. The available sizes are resolved using the theme configuration for the Icon component: + +```js +{ + components: { + Icon: { + sizes: { + '2xs': 16, + 'xs': 20, + 'sm': 24, + 'md': 32, + 'lg': 48, + 'xl': 72, + '2xl': 96 + } + } + } +} +``` + + + + + +```tsx + +``` diff --git a/docs/src/components/ExampleCustomIcon/index.tsx b/docs/src/components/ExampleCustomIcon/index.tsx index 5b8ea70..54bc1eb 100644 --- a/docs/src/components/ExampleCustomIcon/index.tsx +++ b/docs/src/components/ExampleCustomIcon/index.tsx @@ -17,8 +17,8 @@ const CustomIcon = () => ( /> )} - size="xl" - color="black" + size="md" + color="error.700" name="custom-icon" /> );