@blocklet/ui-react/docs/components-utilities-icon.md

Some useful front-end web components that can be used in Blocklets.

# Icon

The `Icon` component is a flexible utility built upon Material-UI's `Avatar` component. It is designed to render icons from multiple sources, including [Iconify](https://iconify.design/) icon strings, image URLs, and character-based "letter avatars". This versatility makes it a standardized component for handling most icon and avatar display needs within an application.

## Props

The `Icon` component accepts the following props:

<x-field-group>
  <x-field data-name="icon" data-type="string" data-required="true">
    <x-field-desc markdown>The primary identifier for the icon. The component intelligently determines how to render it based on the string's format. It can be an Iconify string (e.g., `mdi:home`), a direct image URL, or a simple string to generate a letter avatar (e.g., "U").</x-field-desc>
  </x-field>
  <x-field data-name="size" data-type="number" data-required="false">
    <x-field-desc markdown>Sets a uniform `width` and `height` for the icon container in pixels.</x-field-desc>
  </x-field>
  <x-field data-name="sx" data-type="BoxProps['sx']" data-required="false">
    <x-field-desc markdown>The `sx` prop for custom styling, consistent with Material-UI's system.</x-field-desc>
  </x-field>
  <x-field data-name="..." data-type="AvatarProps" data-required="false">
    <x-field-desc markdown>The component also accepts any other props supported by the Material-UI [Avatar](https://mui.com/material-ui/react-avatar/) component, such as `variant`, `alt`, and `onClick`.</x-field-desc>
  </x-field>
</x-field-group>

## Usage Examples

Here are practical examples demonstrating the different ways to use the `Icon` component.

### Iconify Icon

To display an icon from the Iconify ecosystem, provide its unique string identifier to the `icon` prop. The component will dynamically load and render the corresponding SVG.

```jsx Displaying an Iconify icon icon=mdi:react
import Icon from '@blocklet/ui-react/lib/Icon';

export default function IconifyExample() {
  return <Icon icon="mdi:react" size={48} />;
}
```

This example renders the "react" icon from the Material Design Icons collection.

### Image URL

You can render an image directly by passing its URL to the `icon` prop. The component will detect the URL format and use it as the `src` for an `<img>` tag within the Avatar.

```jsx Rendering an icon from a URL icon=mdi:image
import Icon from '@blocklet/ui-react/lib/Icon';

export default function ImageUrlExample() {
  return <Icon icon="https://www.arcblock.io/image-bin/uploads/eb1cf5d60cd85c42362920c49e3768cb.svg" size={48} />;
}
```

### Letter Avatar

If the `icon` prop receives a string that is neither a valid Iconify icon nor a URL, it will render a letter avatar using the first character of the string. This is useful for user profile placeholders.

```jsx Creating a letter avatar icon=mdi:format-letter-case
import Icon from '@blocklet/ui-react/lib/Icon';

export default function LetterAvatarExample() {
  return <Icon icon="Blocklet" size={48} variant="rounded" sx={{ bgcolor: 'primary.main', color: 'primary.contrastText' }} />;
}
```

In this case, the component will display the letter "B". Note the use of the `variant` and `sx` props, which are passed directly to the underlying Material-UI Avatar.

### Custom Size

The `size` prop provides a convenient way to control the icon's dimensions.

```jsx Adjusting the icon size icon=mdi:ruler
import Icon from '@blocklet/ui-react/lib/Icon';

export default function SizingExample() {
  return (
    <div>
      <Icon icon="mdi:home" size={24} />
      <Icon icon="mdi:home" size={32} />
      <Icon icon="mdi:home" size={48} />
    </div>
  );
}
```

This example shows the same icon rendered at three different sizes.

### Using Avatar Props

Since the `Icon` component is a wrapper around Material-UI's `Avatar`, you can use any `Avatar` prop to customize its appearance. For instance, you can change the shape using the `variant` prop.

```jsx Customizing with Avatar props icon=mdi:shape
import Icon from '@blocklet/ui-react/lib/Icon';

export default function AvatarPropsExample() {
  return (
    <div>
      <Icon icon="B" variant="circular" size={48} sx={{ bgcolor: 'secondary.main' }} />
      <Icon icon="L" variant="rounded" size={48} sx={{ bgcolor: 'success.main' }} />
      <Icon icon="T" variant="square" size={48} sx={{ bgcolor: 'info.main' }} />
    </div>
  );
}
```

This demonstrates how to create circular, rounded, and square avatars.