diff --git a/packages/grafana-ui/src/components/IconButton/IconButton.mdx b/packages/grafana-ui/src/components/IconButton/IconButton.mdx
new file mode 100644
index 00000000000..1d8490952a5
--- /dev/null
+++ b/packages/grafana-ui/src/components/IconButton/IconButton.mdx
@@ -0,0 +1,12 @@
+import { Meta, Story, Preview, Props } from '@storybook/addon-docs/blocks';
+import { IconButton } from './IconButton';
+
+<Meta title="MDX|IconButton" component={IconButton} />
+
+# IconButton
+
+This component looks like just an icon but behaves like a button. It fulfils an action when you click it and has hover and focus states. You can choose which icon size you would like to use. Watch out for where you place this icon, as the hover effect needs to be adjusted with the `surface` prop depending on where it is used.
+
+`IconButton` is best used when an actual button would look out of place, for example when you want to place a solitary clickable icon next to text. An example where an `IconButton` is used in Grafana is the top left back arrow in the panel edit mode.
+
+<Props of={IconButton} />
diff --git a/packages/grafana-ui/src/components/IconButton/IconButton.story.tsx b/packages/grafana-ui/src/components/IconButton/IconButton.story.tsx
index b6128cee333..92092613435 100644
--- a/packages/grafana-ui/src/components/IconButton/IconButton.story.tsx
+++ b/packages/grafana-ui/src/components/IconButton/IconButton.story.tsx
@@ -5,13 +5,16 @@ import { withCenteredStory } from '../../utils/storybook/withCenteredStory';
 import { useTheme } from '../../themes/ThemeContext';
 import { GrafanaTheme } from '@grafana/data';
 import { IconSize, IconName } from '../../types';
+import mdx from './IconButton.mdx';
 
 export default {
   title: 'Buttons/IconButton',
   component: IconButton,
   decorators: [withCenteredStory],
   parameters: {
-    docs: {},
+    docs: {
+      page: mdx,
+    },
   },
 };
 
@@ -59,6 +62,7 @@ function renderScenario(surface: string, theme: GrafanaTheme, sizes: IconSize[],
         }
       `}
     >
+      <div>Surface: {surface}</div>
       {icons.map(icon => {
         return sizes.map(size => (
           <span key={icon + size}>
diff --git a/packages/grafana-ui/src/components/IconButton/IconButton.tsx b/packages/grafana-ui/src/components/IconButton/IconButton.tsx
index b0fcaf89c23..64816944a52 100644
--- a/packages/grafana-ui/src/components/IconButton/IconButton.tsx
+++ b/packages/grafana-ui/src/components/IconButton/IconButton.tsx
@@ -9,12 +9,17 @@ import { Tooltip } from '../Tooltip/Tooltip';
 import { TooltipPlacement } from '../Tooltip/PopoverController';
 
 export interface Props extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  /** Name of the icon **/
   name: IconName;
+  /** Icon size */
   size?: IconSize;
   /** Need this to change hover effect based on what surface it is on */
   surface?: SurfaceType;
+  /** Type od the icon - mono or default */
   iconType?: IconType;
+  /** Tooltip content to display on hover */
   tooltip?: string;
+  /** Position of the tooltip */
   tooltipPlacement?: TooltipPlacement;
 }