Icons

ECMAScript

The package published on npm is transpiled, with Babel, to take into account the supported platforms.


A second version of the components is also published, which you can find under the folder. All the non-official syntax is transpiled to the ECMA-262 standard, nothing more. This can be used to make separate bundles targeting different browsers. Older browsers will require more JavaScript features to be transpiled, which increases the size of the bundle. No polyfills are included for ES2015 runtime features. IE11+ and evergreen browsers support all the necessary features. If you need support for other browsers, consider using .

️ In order to minimize duplication of code in users’ bundles, library authors are strongly discouraged from using the folder.

Accessibility

Icons can convey all sorts of meaningful information, so it’s important that they reach the largest amount of people possible. There are two use cases you’ll want to consider:

  • Decorative Icons are only being used for visual or branding reinforcement. If they were removed from the page, users would still understand and be able to use your page.
  • Semantic Icons are ones that you’re using to convey meaning, rather than just pure decoration. This includes icons without text next to them used as interactive controls — buttons, form elements, toggles, etc.

Decorative SVG Icons

If your icons are purely decorative, you’re already done! The attribute is added so that your icons are properly accessible (invisible).

Semantic SVG Icons

If your icon has semantic meaning, all you need to do is throw in a property. The attribute and the element are added so that your icons are properly accessible.

In the case of focusable interactive elements, like when used with an icon button, you can use the property:

Decorative Font Icons

If your icons are purely decorative, you’re already done! The attribute is added so that your icons are properly accessible (invisible).

Versioning strategy

Stability ensures that reusable components and libraries, tutorials, tools, and learned practices don’t become obsolete unexpectedly. Stability is essential for the ecosystem around Material-UI to thrive.

This document contains the practices that are followed to provide you with a leading-edge UI library, balanced with stability, ensuring that future changes are always introduced in a predictable way.

Material-UI follows Semantic Versioning 2.0.0. Material-UI version numbers have three parts: . The version number is incremented based on the level of change included in the release.

  • Major releases contain significant new features, some but minimal developer assistance is expected during the update. When updating to a new major release, you may need to run update scripts, refactor code, run additional tests, and learn new APIs.
  • Minor releases contain important new features. Minor releases are fully backward-compatible; no developer assistance is expected during update, but you can optionally modify your apps and libraries to begin using new APIs, features, and capabilities that were added in the release.
  • Patch releases are low risk, contain bug fixes and small new features. No developer assistance is expected during update.

CSS

Rule name Global class Description
root .MuiButton-root Styles applied to the root element.
label .MuiButton-label Styles applied to the span element that wraps the children.
text .MuiButton-text Styles applied to the root element if .
textPrimary .MuiButton-textPrimary Styles applied to the root element if and .
textSecondary .MuiButton-textSecondary Styles applied to the root element if and .
outlined .MuiButton-outlined Styles applied to the root element if .
outlinedPrimary .MuiButton-outlinedPrimary Styles applied to the root element if and .
outlinedSecondary .MuiButton-outlinedSecondary Styles applied to the root element if and .
contained .MuiButton-contained Styles applied to the root element if .
containedPrimary .MuiButton-containedPrimary Styles applied to the root element if and .
containedSecondary .MuiButton-containedSecondary Styles applied to the root element if and .
disableElevation .MuiButton-disableElevation Styles applied to the root element if .
focusVisible .Mui-focusVisible Pseudo-class applied to the ButtonBase root element if the button is keyboard focused.
disabled .Mui-disabled Pseudo-class applied to the root element if .
colorInherit .MuiButton-colorInherit Styles applied to the root element if .
textSizeSmall .MuiButton-textSizeSmall Styles applied to the root element if and .
textSizeLarge .MuiButton-textSizeLarge Styles applied to the root element if and .
outlinedSizeSmall .MuiButton-outlinedSizeSmall Styles applied to the root element if and .
outlinedSizeLarge .MuiButton-outlinedSizeLarge Styles applied to the root element if and .
containedSizeSmall .MuiButton-containedSizeSmall Styles applied to the root element if and .
containedSizeLarge .MuiButton-containedSizeLarge Styles applied to the root element if and .
sizeSmall .MuiButton-sizeSmall Styles applied to the root element if .
sizeLarge .MuiButton-sizeLarge Styles applied to the root element if .
fullWidth .MuiButton-fullWidth Styles applied to the root element if .
startIcon .MuiButton-startIcon Styles applied to the startIcon element if supplied.
endIcon .MuiButton-endIcon Styles applied to the endIcon element if supplied.
iconSizeSmall .MuiButton-iconSizeSmall Styles applied to the icon element if supplied and .
iconSizeMedium .MuiButton-iconSizeMedium Styles applied to the icon element if supplied and .
iconSizeLarge .MuiButton-iconSizeLarge Styles applied to the icon element if supplied and .

You can override the style of the component thanks to one of these customization points:

  • With a rule name of the .
  • With a .
  • With a theme and an .

If that’s not sufficient, you can check the implementation of the component for more detail.

RTL icons on iOS

iOS has the concept of a UISemanticContentAttribute that is attached to each view. This can be , , , or . iOS uses this value and the (left-to-right (LTR)/RTL setting of the device presenting the interface to determine the effectiveLayoutDirection of the view. This effectiveLayoutDirection determines whether or not to mirror an image when it is displayed.

By default, images’ semantic content is set to . This causes them to be mirrored in RTL mode. If you do not want an icon to ever be mirrored, you need to explicitly set it to be . Apple calls out some exceptions that should not be mirrored, such as media playback (Fast Forward, rewind, etc.), musical notes, images indicating the passage of time, etc.

Objective-C example:

Swift example:

For more in-depth documentation on how to implement RTL on iOS and macOS, please review Apple’s RTL documentation.

Semantic content was added in iOS 9. If you are supporting earlier versions of iOS, the material internationalization framework backports some of the functionality to iOS 8.

Installing icons from npm

Install the icons using npm package manager.

Icon font for the web

The material icon font is the easiest way to incorporate material icons with web projects. We have packaged all the material icons into a single font that takes advantage of the typographic rendering capabilities of modern browsers so that web developers can easily incorporate these icons with only a few lines of code.

Using the font is not only the most convenient method, but it is efficient and looks great:

  • 900+ icons all from a single, small file.
  • Served from Google Web Font servers or can be self hosted.
  • Supported by all modern web browsers.
  • Colored, sized and positioned entirely with CSS.
  • Vector-based: Looks great at any scale, retina displays, low-dpi display screens.

The icon font weighs in at only 42KB in its smallest woff2 format and 56KB in standard woff format. By comparison, the SVG files compressed with gzip will generally be around 62KB in size, but this can be reduced considerably by compiling only the icons you need into a single SVG file with symbol sprites.

Styling icons in material design

These icons were designed to follow the material design guidelines and they look best when using the recommended icon sizes and colors. The styles below make it easy to apply our recommended sizes, colors, and activity states.

Sizing

Although the icons in the font can be scaled to any size, in accordance with , we recommend them to be shown in either 18, 24, 36 or 48px. The default being 24px.

CSS rules for the standard material design sizing guidelines:

Material icons look best at 24px, but if an icon needs to be displayed in an alternative size, using the above CSS rules can help:

face18px

face24px

face36px

face48px

Coloring

Using the icon font allows for easy styling of an icon in any color. In accordance with , for active icons we recommend using either black at 54% opacity or white at 100% opacity when displaying these on light or dark backgrounds, respectively. If an icon is disabled or inactive, using black at 26% or white at 30% for light and dark backgrounds, respectively.

Here are some examples, using the material CSS styles described above:

Example for drawing an icon on a light background with a dark foreground color:

faceNormal

faceDisabled


Example for drawing an icon on a dark background with a light foreground color:

faceNormal

faceDisabled

To set a custom icon color, define a CSS rule specifying the desired color for the font:

and then use the class when referring to the icon:

faceNormal

Material icons are also available as regular images, both in PNG and SVG formats.

RTL icons on Android

describes in-depth how to implement RTL user interfaces. By default on Android, icons are not mirrored when the layout direction is mirrored. You need to specifically mirror the appropriate icons when needed, either by providing specialized assets for RTL languages, or using framework functionality to mirror the assets.

To provide specialized assets for RTL languages, you can use the qualifier on resource directories, such as . Resources inside such directories will only be used for RTL languages. For devices running Android API 19 or newer, the framework also provides the for Drawables. When this attribute is set to true, the drawable will be automatically mirrored on RTL languages.

Using autoMirrored:

If using autoMirrored or providing alternate Drawable resources isn’t an option, the ImageView scaleX attribute can also be used to mirror drawables (for instance, by providing a RTL-specific layout in a directory).

Mirroring within the layout file:

Lastly, drawables can be mirrored programmatically.

Manually check for layout direction using :

Mirroring ImageView contents programmatically:

CSS

Rule name Global class Description
root .MuiInput-root Styles applied to the root element.
formControl .MuiInput-formControl Styles applied to the root element if the component is a descendant of .
focused .Mui-focused Styles applied to the root element if the component is focused.
disabled .Mui-disabled Styles applied to the root element if .
colorSecondary .MuiInput-colorSecondary Styles applied to the root element if color secondary.
underline .MuiInput-underline Styles applied to the root element if .
error .Mui-error Pseudo-class applied to the root element if .
marginDense .MuiInput-marginDense Styles applied to the element if .
multiline .MuiInput-multiline Styles applied to the root element if .
fullWidth .MuiInput-fullWidth Styles applied to the root element if .
input .MuiInput-input Styles applied to the element.
inputMarginDense .MuiInput-inputMarginDense Styles applied to the element if .
inputMultiline .MuiInput-inputMultiline Styles applied to the element if .
inputTypeSearch .MuiInput-inputTypeSearch Styles applied to the element if .

You can override the style of the component thanks to one of these customization points:

  • With a rule name of the .
  • With a .
  • With a theme and an .

If that’s not sufficient, you can check the implementation of the component for more detail.

Props

Name Type Default Description
action node The action to display. It renders after the message, at the end of the alert.
children node The content of the component.
classes object Override or extend the styles applied to the component. See below for more details.
closeText string ‘Close’ Override the default label for the close popup icon button.For localization purposes, you can use the provided translations.
color ‘error’| ‘info’| ‘success’| ‘warning’ The main color for the alert. Unless provided, the value is taken from the prop.
icon node Override the icon displayed before the children. Unless provided, the icon is mapped to the value of the prop.
iconMapping { error?: node, info?: node, success?: node, warning?: node } The component maps the prop to a range of different icons, for instance success to . If you wish to change this mapping, you can provide your own. Alternatively, you can use the prop to override the icon displayed.
onClose func Callback fired when the component requests to be closed. When provided and no prop is set, a close icon button is displayed that triggers the callback when clicked.Signature:event: The event source of the callback.
role string ‘alert’ The ARIA role attribute of the element.
severity ‘error’| ‘info’| ‘success’| ‘warning’ ‘success’ The severity of the alert. This defines the color and icon used.
variant ‘filled’| ‘outlined’| ‘standard’ ‘standard’ The variant to use.

The is forwarded to the root element.

Any other props supplied will be provided to the root element (Paper).

CSS

Rule name Global class Description
root .MuiSwitch-root Styles applied to the root element.
edgeStart .MuiSwitch-edgeStart Styles applied to the root element if .
edgeEnd .MuiSwitch-edgeEnd Styles applied to the root element if .
switchBase .MuiSwitch-switchBase Styles applied to the internal component’s class.
colorPrimary .MuiSwitch-colorPrimary Styles applied to the internal SwitchBase component’s root element if .
colorSecondary .MuiSwitch-colorSecondary Styles applied to the internal SwitchBase component’s root element if .
sizeSmall .MuiSwitch-sizeSmall Styles applied to the root element if .
checked .Mui-checked Pseudo-class applied to the internal component’s class.
disabled .Mui-disabled Pseudo-class applied to the internal SwitchBase component’s disabled class.
input .MuiSwitch-input Styles applied to the internal SwitchBase component’s input element.
thumb .MuiSwitch-thumb Styles used to create the thumb passed to the internal component prop.
track .MuiSwitch-track Styles applied to the track element.

You can override the style of the component thanks to one of these customization points:

  • With a rule name of the .
  • With a .
  • With a theme and an .

If that’s not sufficient, you can check the implementation of the component for more detail.

CSS

Rule name Global class Description
root .MuiPaginationItem-root Styles applied to the root element.
page .MuiPaginationItem-page Styles applied to the root element if .
sizeSmall .MuiPaginationItem-sizeSmall Styles applied applied to the root element if .
sizeLarge .MuiPaginationItem-sizeLarge Styles applied applied to the root element if .
textPrimary .MuiPaginationItem-textPrimary Styles applied to the root element if and .
textSecondary .MuiPaginationItem-textSecondary Styles applied to the root element if and .
outlined .MuiPaginationItem-outlined Styles applied to the root element if .
outlinedPrimary .MuiPaginationItem-outlinedPrimary Styles applied to the root element if and .
outlinedSecondary .MuiPaginationItem-outlinedSecondary Styles applied to the root element if and .
rounded .MuiPaginationItem-rounded Styles applied to the root element if .
ellipsis .MuiPaginationItem-ellipsis Styles applied to the root element if or .
focusVisible .Mui-focusVisible Pseudo-class applied to the root element if keyboard focused.
disabled .Mui-disabled Pseudo-class applied to the root element if .
selected .Mui-selected Pseudo-class applied to the root element if .
icon .MuiPaginationItem-icon Styles applied to the icon element.

You can override the style of the component thanks to one of these customization points:

  • With a rule name of the .
  • With a .
  • With a theme and an .

If that’s not sufficient, you can check the implementation of the component for more detail.

Props

Name Type Default Description
autoComplete string This prop helps users to fill forms faster, especially on mobile devices. The name can be confusing, as it’s more like an autofill. You can learn more about it .
autoFocus bool If , the element will be focused during the first mount.
classes object Override or extend the styles applied to the component. See below for more details.
color ‘primary’| ‘secondary’ The color of the component. It supports those theme colors that make sense for this component.
defaultValue any The default element value. Use when the component is not controlled.
disabled bool If , the element will be disabled.
disableUnderline bool If , the input will not have an underline.
endAdornment node End for this component.
error bool If , the input will indicate an error. This is normally obtained via context from FormControl.
fullWidth bool false If , the input will take up the full width of its container.
id string The id of the element.
inputComponent elementType ‘input’ The component used for the element. Either a string to use a HTML element or a component.
inputProps object applied to the element.
inputRef ref Pass a ref to the element.
margin ‘dense’| ‘none’ If , will adjust vertical spacing. This is normally obtained via context from FormControl.
multiline bool false If , a textarea element will be rendered.
name string Name attribute of the element.
onChange func Callback fired when the value is changed.Signature:event: The event source of the callback. You can pull out the new value by accessing (string).
placeholder string The short hint displayed in the input before the user enters a value.
readOnly bool It prevents the user from changing the value of the field (not from interacting with the field).
required bool If , the element will be required.
rows number| string Number of rows to display when multiline option is set to true.
rowsMax number| string Maximum number of rows to display when multiline option is set to true.
startAdornment node Start for this component.
type string ‘text’ Type of the element. It should be .
value any The value of the element, required for a controlled component.

The is forwarded to the root element.

Any other props supplied will be provided to the root element (InputBase).

CSS

Rule name Global class Description
root .MuiRating-root Styles applied to the root element.
sizeSmall .MuiRating-sizeSmall Styles applied to the root element if .
sizeLarge .MuiRating-sizeLarge Styles applied to the root element if .
readOnly .MuiRating-readOnly Styles applied to the root element if .
disabled .Mui-disabled Pseudo-class applied to the root element if .
focusVisible .Mui-focusVisible Pseudo-class applied to the root element if keyboard focused.
visuallyhidden .MuiRating-visuallyhidden Visually hide an element.
pristine .MuiRating-pristine Styles applied to the pristine label.
label .MuiRating-label Styles applied to the label elements.
icon .MuiRating-icon Styles applied to the icon wrapping elements.
iconEmpty .MuiRating-iconEmpty Styles applied to the icon wrapping elements when empty.
iconFilled .MuiRating-iconFilled Styles applied to the icon wrapping elements when filled.
iconHover .MuiRating-iconHover Styles applied to the icon wrapping elements when hover.
iconFocus .MuiRating-iconFocus Styles applied to the icon wrapping elements when focus.
iconActive .MuiRating-iconActive Styles applied to the icon wrapping elements when active.
decimal .MuiRating-decimal Styles applied to the icon wrapping elements when decimals are necessary.

You can override the style of the component thanks to one of these customization points:

  • With a rule name of the .
  • With a .
  • With a theme and an .

If that’s not sufficient, you can check the implementation of the component for more detail.

API

Generate a theme base on the options received.

Аргументы

  1. (Object): Takes an incomplete theme object and adds the missing parts.
  2. (Array): Deep merge the arguments with the about to be returned theme.

Generate responsive typography settings based on the options received.

Аргументы

  1. (Object): The theme object to enhance.
  2. (объекта ):
  • Array of breakpoints (identifiers). (Array<String> ): Default to .
  • (Boolean ): Default to . Whether font sizes change slightly so line heights are preserved and align to Material Design’s 4px line height grid. This requires a unitless line height in the theme’s styles.
  • (Number ): Default to . This value determines the strength of font size resizing. The higher the value, the less difference there is between font sizes on small screens. The lower the value, the bigger font sizes for small screens. The value must be greater than 1.
  • (Array<String> ): Default to all. The typography variants to handle.

(Object): The new theme with a responsive typography.

WARNING: Do not use this method in production.

Generates a theme that reduces the amount of warnings inside like .

Requirements

Using restricts the usage of some of our components.

prop

The component used in the prop of the following components need to forward their ref:

Collapse

Otherwise you’ll encounter . See also: .

prop

The of the following components need to forward their ref:

Otherwise the component will not animate properly and you’ll encounter the warning that .

Disable StrictMode compatibility partially

If you still see then you’re probably using a third-party component for which the previously mentioned fixes aren’t applicable. You can fix this by applying . You’ll see deprecation warnings again but these are only warnings while actually breaks the documented behavior of our components.

Аргументы

  1. (Object): Takes an incomplete theme object and adds the missing parts.
  2. (Array): Deep merge the arguments with the about to be returned theme.

Deprecation practices

Sometimes «breaking changes», such as the removal of support for select APIs and features, are necessary.

To make these transitions as easy as possible:

  • The number of breaking changes is minimized, and migration tools provided when possible.
  • The deprecation policy described below is followed, so that you have time to update your apps to the latest APIs and best practices.

Deprecation policy

  • Deprecated features are announced in the changelog, and when possible, with warnings at runtime.
  • When a deprecation is announced, recommended update path is provided.
  • Existing use of a stable API during the deprecation period is supported, so your code will keep working during that period.
  • Peer dependency updates (React) that require changes to your apps are only made in a major release.

Wrapping components


In order to provide the maximum flexibility and performance, we need a way to know the nature of the child elements a component receives. To solve this problem we tag some of the components with a static property when needed.

You may, however, need to wrap a component in order to enhance it, which can conflict with the solution. If you wrap a component, verify if that component has this static property set.

If you encounter this issue, you need to use the same tag for your wrapping component that is used with the wrapped component. In addition, you should forward the properties, as the parent component may need to control the wrapped components props.

Давайте рассмотрим пример:

PNG

PNG is the most traditional way to display icons on the web. Our downloads from the material icons library provide both single and double densities for each icon. They are referred to as and respectively in the download. Icons are also available in the git repository under:

If multiple icons are in use on a web site, creating spritesheets out of the images is recommended. For more information, refer to recommendations in the sprites directory in the git repository.

Icons for Android

PNGs suitable for Android are available from the material icons library. These come in all the supported screen densities so they should look good on any device.

The icons are also available in the material design icons git repository in the same combination of colors and sizes named as follows:

A density-independent VectorDrawable is provided which is supported from Android Lollipop and later:

The Vector Drawable is currently only available as a black 24dp icon. This is for compatibility with our most standard icon size. To render the icon in a different color, use drawable tinting available on Android Lollipop.

When using the Vector Drawable, it may not be necessary to include the xxxhdpi density PNG since it is unlikely a device supporting that screen density does not support Vector Drawables.

Icons for iOS

Material icons also work well within iOS apps. In both the material icons library and git repository, these icons are packaged up in Xcode imagesets which will work easily with Xcode Asset Catalogs (xcassets). These imagesets can be added to any Xcode Asset Catalogs by dragging them into Xcode on to the asset catalog or by copying the folder into the xcasset folder.

The imageset contains the single, double and triple density images (1x, 2x, 3x) so they work on all known iOS screen densities. Both black and white icons are provided, but we recommend using with which will allow the image to be used as an alpha mask that can be tinted to any possible color.

Objective-C example:

Swift Example:

Icons in RTL

Languages such as Arabic and Hebrew are read from right-to-left (RTL). For RTL languages, UIs should be mirrored to display most elements in RTL. When a user interface is mirrored for RTL, some of the icons should also be mirrored. When text, layout, and iconography are mirrored to support right-to-left UIs, anything that relates to time should be depicted as moving from right to left. For example, forward points to the left, and backwards points to the right. However, be mindful that the context in which the icon is placed also influences whether an icon should be mirrored or not.

Icons should only be mirrored if their direction matches other UI elements in RTL mode. When an icon represents visual features of your website that are different in RTL, then the icon should also be mirrored in RTL. For example, if the numbers in a numbered list are on the right side in the RTL language, then the numbers should be on the right side of the mirrored icon.

Note: Icons that include a question mark need to be mirrored in Arabic and Farsi, but not in Hebrew. For an in-depth guidance on this topic, please read the Bidirectionality material design spec article.

Material icons

Google has created over 1,300 official Material icons, each in five different «themes» (see below). For each SVG icon, we export the respective React component from the package. You can search the full list of these icons.

Installation

Install the package in your project directory with:

These components use the Material-UI SvgIcon component to render the SVG path for each icon, and so they have a peer-dependency on the next release of Material-UI.

If you are not already using Material-UI in your project, you can add it with:

Usage

Import icons using one of these two options:

  • Option 1:

  • Option 2:

The safest is Option 1 but Option 2 can yield the best developer experience. Make sure you follow the before using the second approach. The configuration of a Babel plugin is encouraged.

Each icon also has a «theme»: Filled (default), Outlined, Rounded, Two tone and Sharp. If you want to import the icon component with a theme other than default, append the theme name to the icon name. For example icon with:

  • Filled theme (default) is exported as ,
  • Outlined theme is exported as ,
  • Rounded theme is exported as ,
  • Twotone theme is exported as ,
  • Sharp theme is exported as .

CSS

Rule name Global class Description
root .MuiSvgIcon-root Styles applied to the root element.
colorPrimary .MuiSvgIcon-colorPrimary Styles applied to the root element if .
colorSecondary .MuiSvgIcon-colorSecondary Styles applied to the root element if .
colorAction .MuiSvgIcon-colorAction Styles applied to the root element if .
colorError .MuiSvgIcon-colorError Styles applied to the root element if .
colorDisabled .MuiSvgIcon-colorDisabled Styles applied to the root element if .
fontSizeInherit .MuiSvgIcon-fontSizeInherit Styles applied to the root element if .
fontSizeSmall .MuiSvgIcon-fontSizeSmall Styles applied to the root element if .
fontSizeLarge .MuiSvgIcon-fontSizeLarge Styles applied to the root element if .

You can override the style of the component thanks to one of these customization points:

  • With a rule name of the .
  • With a .
  • With a theme and an .

If that’s not sufficient, you can check the implementation of the component for more detail.


С этим читают