[Avatar] Add square variant and documentation (#18116)

docs/pages/api/avatar.md

@@ -32,6 +32,7 @@ You can learn more about the difference by [reading this guide](/guides/minimizi
 | <span class="prop-name">sizes</span> | <span class="prop-type">string</span> | | The `sizes` attribute for the `img` element. |
 | <span class="prop-name">src</span> | <span class="prop-type">string</span> | | The `src` attribute for the `img` element. |
 | <span class="prop-name">srcSet</span> | <span class="prop-type">string</span> | | The `srcSet` attribute for the `img` element. |
+| <span class="prop-name">variant</span> | <span class="prop-type">'circle'<br>&#124;&nbsp;'rounded'<br>&#124;&nbsp;'square'</span> | <span class="prop-default">'circle'</span> | The shape of the avatar. |
 
 The `ref` is forwarded to the root element.
 
@@ -46,6 +47,9 @@ Any other props supplied will be provided to the root element (native element).
 |:-----|:-------------|:------------|
 | <span class="prop-name">root</span> | <span class="prop-name">.MuiAvatar-root</span> | Styles applied to the root element.
 | <span class="prop-name">colorDefault</span> | <span class="prop-name">.MuiAvatar-colorDefault</span> | Styles applied to the root element if there are children and not `src` or `srcSet`.
+| <span class="prop-name">circle</span> | <span class="prop-name">.MuiAvatar-circle</span> | Styles applied to the root element if `variant="circle"`.
+| <span class="prop-name">rounded</span> | <span class="prop-name">.MuiAvatar-rounded</span> | Styles applied to the root element if `variant="rounded"`.
+| <span class="prop-name">square</span> | <span class="prop-name">.MuiAvatar-square</span> | Styles applied to the root element if `variant="square"`.
 | <span class="prop-name">img</span> | <span class="prop-name">.MuiAvatar-img</span> | Styles applied to the img element if either `src` or `srcSet` is defined.
 
 You can override the style of the component thanks to one of these customization points:

docs/src/pages/components/avatars/VariantAvatars.js

@@ -0,0 +1,37 @@
+import React from 'react';
+import { makeStyles } from '@material-ui/core/styles';
+import { deepOrange, green } from '@material-ui/core/colors';
+import Avatar from '@material-ui/core/Avatar';
+import AssignmentIcon from '@material-ui/icons/Assignment';
+
+const useStyles = makeStyles({
+ root: {
+ display: 'flex',
+ '& > * + *': {
+ marginLeft: 16,
+ },
+ },
+ square: {
+ color: '#fff',
+ backgroundColor: deepOrange[500],
+ },
+ rounded: {
+ color: '#fff',
+ backgroundColor: green[500],
+ },
+});
+
+export default function VariantAvatars() {
+ const classes = useStyles();
+
+ return (
+ <div className={classes.root}>
+ <Avatar variant="square" className={classes.square}>
+ N
+ </Avatar>
+ <Avatar variant="rounded" className={classes.rounded}>
+ <AssignmentIcon />
+ </Avatar>
+ </div>
+ );
+}

docs/src/pages/components/avatars/VariantAvatars.tsx

@@ -0,0 +1,37 @@
+import React from 'react';
+import { makeStyles } from '@material-ui/core/styles';
+import { deepOrange, green } from '@material-ui/core/colors';
+import Avatar from '@material-ui/core/Avatar';
+import AssignmentIcon from '@material-ui/icons/Assignment';
+
+const useStyles = makeStyles({
+ root: {
+ display: 'flex',
+ '& > * + *': {
+ marginLeft: 16,
+ },
+ },
+ square: {
+ color: '#fff',
+ backgroundColor: deepOrange[500],
+ },
+ rounded: {
+ color: '#fff',
+ backgroundColor: green[500],
+ },
+});
+
+export default function VariantAvatars() {
+ const classes = useStyles();
+
+ return (
+ <div className={classes.root}>
+ <Avatar variant="square" className={classes.square}>
+ N
+ </Avatar>
+ <Avatar variant="rounded" className={classes.rounded}>
+ <AssignmentIcon />
+ </Avatar>
+ </div>
+ );
+}

docs/src/pages/components/avatars/avatars.md

@@ -24,3 +24,9 @@ Avatars containing simple characters can be created by passing your string as `c
 Icon avatars are created by passing an icon as `children`.
 
 {{"demo": "pages/components/avatars/IconAvatars.js"}}
+
+## Variants
+
+If you need square or rounded avatars, use the `variant` prop.
+
+{{"demo": "pages/components/avatars/VariantAvatars.js"}}

packages/material-ui/src/Avatar/Avatar.d.ts

@@ -8,14 +8,15 @@ export interface AvatarTypeMap<P = {}, D extends React.ElementType = 'div'> {
  sizes?: string;
  src?: string;
  srcSet?: string;
+ variant?: 'circle' | 'rounded' | 'square';
  };
  defaultComponent: D;
  classKey: AvatarClassKey;
 }
 
 declare const Avatar: OverridableComponent<AvatarTypeMap>;
 
-export type AvatarClassKey = 'root' | 'colorDefault' | 'img';
+export type AvatarClassKey = 'root' | 'colorDefault' | 'circle' | 'rounded' | 'square' | 'img';
 
 export type AvatarProps<
  D extends React.ElementType = AvatarTypeMap['defaultComponent'],

packages/material-ui/src/Avatar/Avatar.js

@@ -26,6 +26,16 @@ export const styles = theme => ({
  backgroundColor:
  theme.palette.type === 'light' ? theme.palette.grey[400] : theme.palette.grey[600],
  },
+ /* Styles applied to the root element if `variant="circle"`. */
+ circle: {},
+ /* Styles applied to the root element if `variant="rounded"`. */
+ rounded: {
+ borderRadius: theme.shape.borderRadius,
+ },
+ /* Styles applied to the root element if `variant="square"`. */
+ square: {
+ borderRadius: 0,
+ },
  /* Styles applied to the img element if either `src` or `srcSet` is defined. */
  img: {
  width: '100%',
@@ -47,6 +57,7 @@ const Avatar = React.forwardRef(function Avatar(props, ref) {
  sizes,
  src,
  srcSet,
+ variant = 'circle',
  ...other
  } = props;
 
@@ -73,6 +84,7 @@ const Avatar = React.forwardRef(function Avatar(props, ref) {
  className={clsx(
  classes.root,
  classes.system,
+ classes[variant],
  {
  [classes.colorDefault]: !img,
  },
@@ -128,6 +140,10 @@ Avatar.propTypes = {
  * The `srcSet` attribute for the `img` element.
  */
  srcSet: PropTypes.string,
+ /**
+ * The shape of the avatar.
+ */
+ variant: PropTypes.oneOf(['circle', 'rounded', 'square']),
 };
 
 export default withStyles(styles, { name: 'MuiAvatar' })(Avatar);