Ícones

Orientação e sugestões para usar ícones com o Material-UI.

Material-UI fornece suporte de ícones de três maneiras:

Standardized Material Icons exported as React components (SVG icons).
Com o componente SvgIcon, um wrapper React para ícones SVG customizados.
Com o componente Icon, um wrapper React para ícones de fonte customizados.

Material SVG icons

Google has created over 2,000 official Material icons, each in five different "themes" (see below). Para cada ícone SVG, exportamos o respectivo componente React do pacote @material-ui/icons. You can search the full list of these icons.

Instalação

To install and save in your package.json dependencies, run the command below using npm:

npm install @mui/icons-material

Or yarn:

yarn add @mui/icons-material

These components use the MUI SvgIcon component to render the SVG path for each icon, and so have a peer-dependency on @mui/material.

If you aren't already using Material UI in your project, you can add it following the installation guide.

Uso

Import icons using one of these two options:

Opção 1:

import AccessAlarmIcon from '@mui/icons-material/AccessAlarm';
import ThreeDRotation from '@mui/icons-material/ThreeDRotation';

Opção 2:

import { AccessAlarm, ThreeDRotation } from '@mui/icons-material';

The safest for bundle size is Option 1, but some developers prefer Option 2. Make sure you follow the minimizing bundle size guide before using the second approach.

Each Material icon also has a "theme": Filled (default), Outlined, Rounded, Two-tone, and Sharp. To import the icon component with a theme other than the default, append the theme name to the icon name. For example @mui/icons-material/Delete icon with:

Tema Filled (preenchido que é o padrão) é exportado como @material-ui/icons/Delete,
Tema Outlined (contornado) é exportado como @material-ui/icons/DeleteOutlined,
Tema Rounded (arredondado) é exportado como @material-ui/icons/DeleteRounded,
Tema Two tone (dois tons) é exportado como @material-ui/icons/DeleteTwoTone,
Tema Sharp (pontiagudo) é exportado como @material-ui/icons/DeleteSharp.

Filled

Outlined

Rounded

Two Tone

Sharp

Edge-cases

Testando

For testing purposes, each icon exposed from @mui/icons-material has a data-testid attribute with the name of the icon. For instance:

import DeleteIcon from '@mui/icons-material/Delete';

has the following attribute once mounted:

<svg data-testid="DeleteIcon"></svg>

SvgIcon

If you need a custom SVG icon (not available in the Material Icons) you can use the SvgIcon wrapper. This component extends the native <svg> element:

Ele vem internamente com a acessibilidade.
Os elementos SVG devem ser dimensionados para uma visualização de 24x24px, de modo que o ícone resultante possa ser usado como está, ou incluído como filho para outros componentes de Material-UI que usam ícones. This can be customized with the viewBox attribute. To inherit the viewBox value from the original image, the inheritViewBox prop can be used.
Por padrão, o componente herda a cor atual. Opcionalmente, você pode aplicar uma das cores do tema usando a propriedade color.

function HomeIcon(props) {
  return (
    <SvgIcon {...props}>
      <path d="M10 20v-6h4v6h5v-8h3L12 3 2 12h3v8z" />
    </SvgIcon>
  );
}

Cor

<HomeIcon />
<HomeIcon color="primary" />
<HomeIcon color="secondary" />
<HomeIcon color="success" />
<HomeIcon color="action" />
<HomeIcon color="disabled" />
<HomeIcon sx={{ color: pink[500] }} />

<HomeIcon />
<HomeIcon color="primary" />
<HomeIcon color="secondary" />
<HomeIcon color="success" />
<HomeIcon color="action" />
<HomeIcon color="disabled" />
<HomeIcon sx={{ color: pink[500] }} />

Press Enter to start editing

Tamanho

<HomeIcon fontSize="small" />
<HomeIcon />
<HomeIcon fontSize="large" />
<HomeIcon sx={{ fontSize: 40 }} />

<HomeIcon fontSize="small" />
<HomeIcon />
<HomeIcon fontSize="large" />
<HomeIcon sx={{ fontSize: 40 }} />

Press Enter to start editing

Propriedade Componente

You can use the SvgIcon wrapper even if your icons are saved in the .svg format. svgr has loaders to import SVG files and use them as React components. For example, with webpack:

// webpack.config.js
{
  test: /\.svg$/,
  use: ['@svgr/webpack'],
}

// ---
import StarIcon from './star.svg';

<SvgIcon component={StarIcon} inheritViewBox />

It's also possible to use it with "url-loader" or "file-loader". This is the approach used by Create React App.

// webpack.config.js
{
  test: /\.svg$/,
  use: ['@svgr/webpack', 'url-loader'],
}

// ---
import { ReactComponent as StarIcon } from './star.svg';

<SvgIcon component={StarIcon} inheritViewBox />

createSvgIcon

The createSvgIcon utility component is used to create the Material Icons. It can be used to wrap an SVG path with an SvgIcon component.

const HomeIcon = createSvgIcon(
  <path d="M10 20v-6h4v6h5v-8h3L12 3 2 12h3v8z" />,
  'Home',
);

<HomeIcon />
<HomeIcon color="primary" />

<HomeIcon />
<HomeIcon color="primary" />

Press Enter to start editing

Fonte Awesome

If you find that there are layout issues when using FontAwesomeIcon from @fortawesome/react-fontawesome, you can try passing the Font Awesome SVG data directly to SvgIcon.

Below is a comparison of the FontAwesomeIcon component and a wrapped SvgIcon component.

<IconButton aria-label="Example">
  <FontAwesomeIcon icon={faEllipsisV} />
</IconButton>
<IconButton aria-label="Example">
  <FontAwesomeSvgIcon icon={faEllipsisV} />
</IconButton>
<Button variant="contained" startIcon={<FontAwesomeIcon icon={faInfo} />}>
  Example
</Button>
<Button variant="contained" startIcon={<FontAwesomeSvgIcon icon={faInfo} />}>
  Example
</Button>

<IconButton aria-label="Example">
  <FontAwesomeIcon icon={faEllipsisV} />
</IconButton>
<IconButton aria-label="Example">
  <FontAwesomeSvgIcon icon={faEllipsisV} />
</IconButton>
<Button variant="contained" startIcon={<FontAwesomeIcon icon={faInfo} />}>
  Example
</Button>
<Button variant="contained" startIcon={<FontAwesomeSvgIcon icon={faInfo} />}>
  Example
</Button>

Press Enter to start editing

FontAwesomeIcon's fullWidth prop can also be used to approximate the correct dimensions, but it isn't perfect.

Fonte Material icons

MDI

materialdesignicons.com provides over 2,000 icons. For the wanted icon, copy the SVG path they provide, and use it as the child of the SvgIcon component, or with createSvgIcon().

Note: mdi-material-ui has already wrapped each of these SVG icons with the SvgIcon component, so you don't have to do it yourself.

Ícone (ícones de fonte)

The Icon component will display an icon from any icon font that supports ligatures. As a prerequisite, you must include one, such as the Material Icons font in your project. To use an icon simply wrap the icon name (font ligature) with the Icon component, for example:

import Icon from '@mui/material/Icon';

<Icon>star</Icon>;

By default, an Icon will inherit the current text color. Optionally, you can set the icon color using one of the theme color properties: primary, secondary, action, error & disabled.

Font Material Icons

Icon will by default set the correct base class name for the Material Icons font (filled variant). All you need to do is load the font, for instance, via Google Web Fonts:

<link
  rel="stylesheet"
  href="https://fonts.googleapis.com/icon?family=Material+Icons"
/>

<Icon>add_circle</Icon>
<Icon color="primary">add_circle</Icon>
<Icon sx={{ color: green[500] }}>add_circle</Icon>
<Icon fontSize="small">add_circle</Icon>
<Icon sx={{ fontSize: 30 }}>add_circle</Icon>

<Icon>add_circle</Icon>
<Icon color="primary">add_circle</Icon>
<Icon sx={{ color: green[500] }}>add_circle</Icon>
<Icon fontSize="small">add_circle</Icon>
<Icon sx={{ fontSize: 30 }}>add_circle</Icon>

Press Enter to start editing

Fonte customizada

For other fonts, you can customize the baseline class name using the baseClassName prop. For instance, you can display two-tone icons with Material Design:

import Icon from '@mui/material/Icon';

<link
  rel="stylesheet"
  href="https://fonts.googleapis.com/css?family=Material+Icons+Two+Tone"
  // Import the two tones MD variant                           ^^^^^^^^
/>;

<Icon baseClassName="material-icons-two-tone">add_circle</Icon>

<Icon baseClassName="material-icons-two-tone">add_circle</Icon>

Press Enter to start editing

Nome da classe base global

Modifying the baseClassName prop for each component usage is repetitive. You can change the default prop globally with the theme

const theme = createTheme({
  components: {
    MuiIcon: {
      defaultProps: {
        // Replace the `material-icons` default value.
        baseClassName: 'material-icons-two-tone',
      },
    },
  },
});

Then, you can use the two-tone font directly:

<Icon>add_circle</Icon>

Fonte Awesome

Font Awesome can be used with the Icon component as follows:

<Icon baseClassName="fas" className="fa-plus-circle" />
<Icon baseClassName="fas" className="fa-plus-circle" color="primary" />
<Icon
  baseClassName="fas"
  className="fa-plus-circle"
  sx={{ color: green[500] }}
/>
<Icon baseClassName="fas" className="fa-plus-circle" fontSize="small" />
<Icon baseClassName="fas" className="fa-plus-circle" sx={{ fontSize: 30 }} />

<Icon baseClassName="fas" className="fa-plus-circle" />
<Icon baseClassName="fas" className="fa-plus-circle" color="primary" />
<Icon
  baseClassName="fas"
  className="fa-plus-circle"
  sx={{ color: green[500] }}
/>
<Icon baseClassName="fas" className="fa-plus-circle" fontSize="small" />
<Icon baseClassName="fas" className="fa-plus-circle" sx={{ fontSize: 30 }} />

Press Enter to start editing

Note that the Font Awesome icons weren't designed like the Material Icons (compare the two previous demos). The fa icons are cropped to use all the space available. You can adjust for this with a global override:

const theme = createTheme({
  components: {
    MuiIcon: {
      styleOverrides: {
        root: {
          // Match 24px = 3 * 2 + 1.125 * 16
          boxSizing: 'content-box',
          padding: 3,
          fontSize: '1.125rem',
        },
      },
    },
  },
});

Call me

<ThemeProvider theme={theme}>
  <Chip icon={<MdPhone />} label="Call me" />
  <Chip icon={<Icon className="fas fa-phone-alt" />} label="Call me" />
</ThemeProvider>

<ThemeProvider theme={theme}>
  <Chip icon={<MdPhone />} label="Call me" />
  <Chip icon={<Icon className="fas fa-phone-alt" />} label="Call me" />
</ThemeProvider>

Press Enter to start editing

Fonte vs SVG. Qual abordagem usar?

Both approaches work fine, however there are some subtle differences, especially in terms of performance and rendering quality. Whenever possible SVG is preferred as it allows code splitting, supports more icons, and renders faster and better.

For more details, take a look at why GitHub migrated from font icons to SVG icons.

Acessibilidade

Icons can convey all sorts of meaningful information, so it's important to ensure they are accessible where appropriate. There are two use cases you'll want to consider:

Ícones decorativos que são usados apenas para reforço visual ou de marca. Se eles forem removidos da página, os usuários ainda entenderiam e poderiam usar sua página.
Semantic icons are ones that you're using to convey meaning, rather than just pure decoration. Isso inclui ícones sem texto ao lado deles que são usados como controles interativos — botões, elementos de forma, toggles, etc.

Ícones decorativos

If your icons are purely decorative, you're already done! The aria-hidden=true attribute is added so that your icons are properly accessible (invisible).

Ícones semânticos

Ícones SVG semânticos

You should include the titleAccess prop with a meaningful value. The role="img" attribute and the <title> element are added so that your icons are correctly accessible.

In the case of focusable interactive elements, for example when used with an icon button, you can use the aria-label prop:

import IconButton from '@mui/material/IconButton';
import SvgIcon from '@mui/material/SvgIcon';

// ...

<IconButton aria-label="delete">
  <SvgIcon>
    <path d="M20 12l-1.41-1.41L13 16.17V4h-2v12.17l-5.58-5.59L4 12l8 8 8-8z" />
  </SvgIcon>
</IconButton>;

Ícones de fonte semânticos

You need to provide a text alternative that is only visible to assistive technologies.

import Box from '@mui/material/Box';
import Icon from '@mui/material/Icon';
import { visuallyHidden } from '@mui/utils';

// ...

<Icon>add_circle</Icon>
<Box component="span" sx={visuallyHidden}>Create a user</Box>

Referência

https://www.tpgi.com/using-aria-enhance-svg-accessibility/

API

See the documentation below for a complete reference to all of the props and classes available to the components mentioned here.