diff --git a/packages/core/src/components/avatar/readme.md b/packages/core/src/components/avatar/readme.md
index 362c20c044..627e32ce5d 100644
--- a/packages/core/src/components/avatar/readme.md
+++ b/packages/core/src/components/avatar/readme.md
@@ -1,7 +1,28 @@
 # ion-avatar
 
-An Avatar is a component that creates a circular image for an item.
-Avatars can be placed on the left or right side of an item with the `item-start` or `item-end` directive.
+Avatars are circular components that usually wrap an image or icon. They can be used to represent a person or an object.
+
+Avatars can be used by themselves or inside of any element. If placed inside of an `ion-chip` or `ion-item`, the avatar will resize to fit the parent component. To position an avatar on the left or right side of an item, set the slot to `start` or `end`, respectively.
+
+```html
+<ion-avatar>
+  <img src="https://gravatar.com/avatar/dba6bae8c566f9d4041fb9cd9ada7741?d=identicon&f=y">
+</ion-avatar>
+
+<ion-chip>
+  <ion-avatar>
+    <img src="https://gravatar.com/avatar/dba6bae8c566f9d4041fb9cd9ada7741?d=identicon&f=y">
+  </ion-avatar>
+  <ion-label>Chip Avatar</ion-label>
+</ion-chip>
+
+<ion-item>
+  <ion-avatar slot="start">
+    <img src="https://gravatar.com/avatar/dba6bae8c566f9d4041fb9cd9ada7741?d=identicon&f=y">
+  </ion-avatar>
+  <ion-label>Item Avatar</ion-label>
+</ion-item>
+```
 
 
 <!-- Auto Generated Below -->