diff --git a/packages/grafana-ui/src/components/BigValue/BigValue.mdx b/packages/grafana-ui/src/components/BigValue/BigValue.mdx
new file mode 100644
index 00000000000..46ad7bf86b9
--- /dev/null
+++ b/packages/grafana-ui/src/components/BigValue/BigValue.mdx
@@ -0,0 +1,70 @@
+import { Meta, Story, Preview, Props } from '@storybook/addon-docs/blocks';
+import { BigValue } from './BigValue';
+
+<Meta title="MDX|BigValue" component={BigValue} />
+
+# BigValue
+Component for showing a value based on a [DisplayValue](https://grafana.com/docs/grafana/latest/packages_api/data/displayvalue/#displayvalue-interface).
+
+### Display properties
+There are a few properties that will determine the look of the BigValue.
+
+#### Justify mode
+There are two modes for aligning text, auto and center.
+
+#### Graph mode
+You can control graph shown in BigValue with the `GraphMode` property. `GraphMode.Area` renders a
+graph in the behind the value. `GrapMode.None` will hide it.
+
+#### Color mode
+`ColorMode` controls which part of the component that should have the color from thresholds or field config,
+`ColorMode.Background` and `ColorMode.Value`.
+
+Note, `ColorMode.Value` will only set the color for the value.
+
+#### Text mode
+There are four variants to render text:
+
+ * `TextMode.Auto` - Show value and name if there's more than on BigValue in the same pane.
+ * `TextMode.Value` - Show only the value.
+ * `TextMode.ValueAndName` - Show value and the name.
+ * `TextMode.None` - Do not show any value or name.
+
+
+
+### Example usage
+An example usage is in the [Stat panel](https://grafana.com/docs/grafana/latest/panels/visualizations/stat-panel/).
+
+```tsx
+import { DisplayValue } from '@grafana/data';
+import {
+  BigValue,
+  BigValueColorMode,
+  BigValueGraphMode,
+  BigValueJustifyMode,
+  BigValueTextMode,
+  useTheme
+} from '@grafana/ui';
+
+const bigValue: DisplayValue = {
+  color: 'red',
+  value: '5000',
+  numeric: 5000,
+  title: 'Volume'
+};
+
+return (
+  <BigValue
+    theme={useTheme()}
+    justifyMode={BigValueJustifyMode.Auto}
+    graphMode={BigValueGraphMode.Area}
+    colorMode={BigValueColorMode.Value}
+    textMode={BigValueTextMode.Auto}
+    value={bigValue}
+  />
+);
+
+
+```
+### Props
+<Props of={BigValue} />
diff --git a/packages/grafana-ui/src/components/BigValue/BigValue.story.tsx b/packages/grafana-ui/src/components/BigValue/BigValue.story.tsx
index 8ec60ce3277..62bad8c3ca4 100644
--- a/packages/grafana-ui/src/components/BigValue/BigValue.story.tsx
+++ b/packages/grafana-ui/src/components/BigValue/BigValue.story.tsx
@@ -1,7 +1,9 @@
-import { text, select, number, color } from '@storybook/addon-knobs';
-import { BigValue, BigValueColorMode, BigValueGraphMode, BigValueTextMode } from '@grafana/ui';
+import React from 'react';
+import { color, number, select, text } from '@storybook/addon-knobs';
+import { BigValue, BigValueColorMode, BigValueGraphMode, BigValueJustifyMode, BigValueTextMode } from './BigValue';
 import { withCenteredStory } from '../../utils/storybook/withCenteredStory';
-import { renderComponentWithTheme } from '../../utils/storybook/withTheme';
+import mdx from './BigValue.mdx';
+import { useTheme } from '../../themes';
 
 const getKnobs = () => {
   return {
@@ -9,6 +11,7 @@ const getKnobs = () => {
     title: text('title', 'Total Earnings'),
     colorMode: select('Color mode', [BigValueColorMode.Value, BigValueColorMode.Background], BigValueColorMode.Value),
     graphMode: select('Graph mode', [BigValueGraphMode.Area, BigValueGraphMode.None], BigValueGraphMode.Area),
+    justifyMode: select('Justify', [BigValueJustifyMode.Auto, BigValueJustifyMode.Center], BigValueJustifyMode.Auto),
     width: number('Width', 400, { range: true, max: 800, min: 200 }),
     height: number('Height', 300, { range: true, max: 800, min: 200 }),
     color: color('Value color', 'red'),
@@ -24,34 +27,44 @@ export default {
   title: 'Visualizations/BigValue',
   component: BigValue,
   decorators: [withCenteredStory],
+  parameters: {
+    docs: {
+      page: mdx,
+    },
+  },
 };
 
 export const basic = () => {
-  const { value, title, colorMode, graphMode, height, width, color, textMode } = getKnobs();
+  const { value, title, colorMode, graphMode, height, width, color, textMode, justifyMode } = getKnobs();
+  const sparkline = {
+    xMin: 0,
+    xMax: 5,
+    data: [
+      [0, 10],
+      [1, 20],
+      [2, 15],
+      [3, 25],
+      [4, 5],
+      [5, 10],
+    ],
+  };
 
-  return renderComponentWithTheme(BigValue, {
-    width: width,
-    height: height,
-    colorMode: colorMode,
-    graphMode: graphMode,
-    textMode,
-    value: {
-      text: value,
-      numeric: 5022,
-      color: color,
-      title,
-    },
-    sparkline: {
-      minX: 0,
-      maxX: 5,
-      data: [
-        [0, 10],
-        [1, 20],
-        [2, 15],
-        [3, 25],
-        [4, 5],
-        [5, 10],
-      ],
-    },
-  });
+  return (
+    <BigValue
+      theme={useTheme()}
+      width={width}
+      height={height}
+      colorMode={colorMode}
+      graphMode={graphMode}
+      textMode={textMode}
+      justifyMode={justifyMode}
+      value={{
+        text: value,
+        numeric: 5022,
+        color: color,
+        title,
+      }}
+      sparkline={graphMode === BigValueGraphMode.None ? undefined : sparkline}
+    />
+  );
 };
diff --git a/packages/grafana-ui/src/components/BigValue/BigValue.tsx b/packages/grafana-ui/src/components/BigValue/BigValue.tsx
index 00fd9011df5..41fdc774a3b 100644
--- a/packages/grafana-ui/src/components/BigValue/BigValue.tsx
+++ b/packages/grafana-ui/src/components/BigValue/BigValue.tsx
@@ -44,16 +44,27 @@ export enum BigValueTextMode {
 }
 
 export interface Props extends Themeable {
+  /** Height of the component */
   height: number;
+  /** Width of the component */
   width: number;
+  /** Value displayed as Big Value */
   value: DisplayValue;
+  /** Sparkline values for showing a graph under/behind the value  */
   sparkline?: BigValueSparkline;
+  /** onClick handler for the value */
   onClick?: React.MouseEventHandler<HTMLElement>;
+  /** Custom styling */
   className?: string;
+  /** Color mode for coloring the value or the background */
   colorMode: BigValueColorMode;
+  /** Show a graph behind/under the value */
   graphMode: BigValueGraphMode;
+  /** Auto justify value and text or center it */
   justifyMode?: BigValueJustifyMode;
+  /** Factors that should influence the positioning of the text  */
   alignmentFactors?: DisplayValueAlignmentFactors;
+  /** Specify which text should be visible in the BigValue */
   textMode?: BigValueTextMode;
 
   /**
@@ -70,7 +81,6 @@ export class BigValue extends PureComponent<Props> {
 
   render() {
     const { onClick, className } = this.props;
-
     const layout = buildLayout(this.props);
     const panelStyles = layout.getPanelStyles();
     const valueAndTitleContainerStyles = layout.getValueAndTitleContainerStyles();