diff --git a/src/components/base/breadcrumb/breadcrumb.md b/src/components/base/breadcrumb/breadcrumb.md
index 8a8b8b320e044dc729ea659aa22585063f58a3b5..4f4ac46ae91adbf983ba2239d804fae85e045c21 100644
--- a/src/components/base/breadcrumb/breadcrumb.md
+++ b/src/components/base/breadcrumb/breadcrumb.md
@@ -1,5 +1,23 @@
 ## Usage
 
+The `GlBreadcrumb` component comes with a smart auto-resize feature. When there is not enough space
+to show all breadcrumb `items` in a single row, the component moves items into an ellipsis dropdown,
+starting with the first one. The last breadcrumb item (which represents the current page) stays
+always visible.
+
+### Auto-resize
+
+**Important:** For the auto-resize to function correctly it is necessary that the `GlBreadcrumb`
+component itself takes all the horizontal space it can get. Since the component has no way of
+knowing in which CSS `display` mode (block, flex, grid) it is used, you have to give it the
+corresponding CSS rule yourself.
+
+**Example:** In a flexbox layout, allow the component to `flex-grow`:
+
+```js
+<gl-breadcrumb class="gl-grow" :items="items" />
+```
+
 ### `items` prop
 
 This component also allows for optional avatars on each item.