Skip to content

Commit

Permalink
Improve Icon component docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@maurobender
maurobender committed Sep 29, 2022
1 parent a63c486 commit 2a21594
Show file tree
Hide file tree
Showing 2 changed files with 122 additions and 93 deletions.
211 changes: 120 additions & 91 deletions docs/docs/components/icon.md
View file
Original file line number Diff line number Diff line change
@@ -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';
Expand All @@ -19,7 +20,7 @@ import { Icon } from '@amalgama/react-native-ui-kit';
<CodePreview>
<Icon
size="md"
color="white"
color="black"
rounded="full"
name="plus"
/>
Expand All @@ -28,120 +29,54 @@ import { Icon } from '@amalgama/react-native-ui-kit';
```jsx
<Icon
size="md"
color="white"
color="black"
padding="2"
rounded="full"
name="plus"
/>
```

## 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:

<CodePreview>
<Icon as={EvilIcons} name="like" size="xl" color="white" />
</CodePreview>

```tsx
import EvilIcons from 'react-native-vector-icons/EvilIcons';

<Icon as={EvilIcons} name="like" size="xl" color="white" />
```
## 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:

<CodePreview>
<Icon as={Ionicons} name="swap-vertical-outline" size="xl" color="white" />
<Icon as={FontAwesomeIcon} name="rocket" size="md" color="information.900" />
</CodePreview>

```tsx
import Ionicons from 'react-native-vector-icons/Ionicons';

<Icon as={Ionicons} name="swap-vertical-outline" size="xl" color="white" />
```


### 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
}
}
}
}
<Icon as={FontAwesomeIcon} name="rocket" size="md" color="information.900" />
```

<CodePreview>
<Icon size="2xl" name="plus" color="white" />
</CodePreview>

```tsx
<Icon size="2xl" name="plus" color="white" />
```

### 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.
:::

<CodePreview>
<Icon color="accent.900" as={Ionicons} size="xl" name="umbrella-outline" />
</CodePreview>
## Use your own custom SVG icons

```tsx
<Icon color="accent.900" as={Ionicons} size="xl" name="umbrella-outline" />
```

## 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

<CodePreview>
<ExampleCustomIcon/>
</CodePreview>

### 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} ) => (
<Svg
width={size}
height={size}
Expand All @@ -155,7 +90,8 @@ const AlertCircle = ({size, color, ...props}) => (
fill={color}
/>
</Svg>
)
);

export default AlertCircle;
```

Expand All @@ -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 <Icon {...props} />
Expand All @@ -179,21 +117,112 @@ export default MyIconLib;
import { Icon } from '@amalgama/react-native-ui-kit';
import MyIconLib from './MyIconLib';

<Icon as={MyIconLib} name="alert-circle" size="xl" color="black">

// Use it as any other icon library
<Icon as={MyIconLib} name="alert-circle" size="md" color="error.700" />
```

### 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';


<Icon
as={AlertCircle}
size="xl"
color="black"
name="this prop will not be used"
/>
```

:::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:

<CodePreview>
<Icon as={EvilIcons} name="like" size="md" />
</CodePreview>

```tsx
import EvilIcons from 'react-native-vector-icons/EvilIcons';

<Icon as={EvilIcons} name="like" size="md" />
```

### 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.

<CodePreview>
<Icon as={Ionicons} name="swap-vertical-outline" size="md"/>
</CodePreview>

```tsx
import Ionicons from 'react-native-vector-icons/Ionicons';

<Icon as={Ionicons} name="swap-vertical-outline" size="md" />
```

### color

The color of the Icon. The resulting color is resolved using the current theme's configuration and passed to the `as` component.

<CodePreview>
<Icon color="accent.900" as={Ionicons} size="md" name="umbrella-outline" />
</CodePreview>

```tsx
<Icon color="accent.900" as={Ionicons} size="md" name="umbrella-outline" />
```

### 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
}
}
}
}
```

<CodePreview>
<Icon size="xl" name="plus" color="black" />
</CodePreview>

```tsx
<Icon size="xl" name="plus" color="black" />
```
4 changes: 2 additions & 2 deletions docs/src/components/ExampleCustomIcon/index.tsx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,8 @@ const CustomIcon = () => (
/>
</Svg>
)}
size="xl"
color="black"
size="md"
color="error.700"
name="custom-icon"
/> );

Expand Down

0 comments on commit 2a21594

Please sign in to comment.