diff --git a/src-docs/src/views/theme/consuming_emotion_theme.tsx b/src-docs/src/views/theme/consuming_emotion_theme.tsx
new file mode 100644
index 00000000000..88cefedf66b
--- /dev/null
+++ b/src-docs/src/views/theme/consuming_emotion_theme.tsx
@@ -0,0 +1,49 @@
+import React from 'react';
+import { ThemeProvider, css } from '@emotion/react';
+import { EuiIcon, EuiText } from '../../../../src';
+
+export default () => {
+ return (
+
+ css`
+ background-color: ${euiTheme.colors.lightestShade};
+ padding: ${euiTheme.size.l};
+ `}
+ >
+ ({
+ color:
+ colorMode === 'LIGHT'
+ ? euiTheme.colors.primary
+ : euiTheme.colors.accent,
+ })}
+ />{' '}
+ This box sets its icon color, background color, and padding via Emotion
+ theme context
+
+
+
+ css`
+ color: ${theme.brandColor};
+ background-color: ${theme.backgroundColor};
+ padding: ${theme.padding};
+ `}
+ >
+ This box sets its own Emotion ThemeProvider and theme variables
+
+
+
+ );
+};
diff --git a/src-docs/src/views/theme/theme_example.js b/src-docs/src/views/theme/theme_example.js
index 7b469e1406b..969a9f6c230 100644
--- a/src-docs/src/views/theme/theme_example.js
+++ b/src-docs/src/views/theme/theme_example.js
@@ -12,6 +12,9 @@ const consumingSource = require('!!raw-loader!./consuming');
import { ConsumingHOC } from './consuming_hoc';
const consumingHOCSource = require('!!raw-loader!./consuming_hoc');
+import ConsumingEmotionTheme from './consuming_emotion_theme';
+const consumingEmotionThemeSource = require('!!raw-loader!./consuming_emotion_theme');
+
import OverrideSimple from './override_simple';
const overrideSimpleSource = require('!!raw-loader!./override_simple');
@@ -154,6 +157,36 @@ export const ThemeExample = {
),
demo: ,
},
+ {
+ title: "Consuming with Emotion's theming",
+ source: [
+ {
+ type: GuideSectionTypes.TSX,
+ code: consumingEmotionThemeSource,
+ },
+ ],
+ text: (
+ <>
+
+ EuiThemeProvider by default sets an{' '}
+
+ Emotion theme context
+ {' '}
+ with the results of useEuiTheme(). This is a
+ syntactical sugar convenience that allows you to take advantage of
+ Emotion's styled syntax, or use a function in the{' '}
+ css prop.
+
+
+ If you prefer to use or access your own custom Emotion theme, you
+ can completely override EUI's passed theme at any time with your own{' '}
+ ThemeProvider - see the second box below for an
+ example.
+
+
+ ),
+ demo: ,
+ },
{
title: 'Simple instance overrides',
source: [
diff --git a/src/custom_typings/emotion.d.ts b/src/custom_typings/emotion.d.ts
new file mode 100644
index 00000000000..53579effe97
--- /dev/null
+++ b/src/custom_typings/emotion.d.ts
@@ -0,0 +1,17 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import '@emotion/react';
+import { UseEuiTheme } from '../services/theme';
+
+/**
+ * @see https://emotion.sh/docs/typescript#define-a-theme
+ */
+declare module '@emotion/react' {
+ export interface Theme extends UseEuiTheme {}
+}
diff --git a/src/services/theme/emotion.test.tsx b/src/services/theme/emotion.test.tsx
new file mode 100644
index 00000000000..b3c8cba2af1
--- /dev/null
+++ b/src/services/theme/emotion.test.tsx
@@ -0,0 +1,84 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import React from 'react';
+import { ThemeProvider } from '@emotion/react';
+import { render } from '../../test/rtl';
+
+import { EuiTextColor } from '../../components/text';
+import { EuiEmotionThemeProvider } from './emotion';
+
+describe('EuiEmotionThemeProvider', () => {
+ it("allows consumers to use Emotion's theme context by default", () => {
+ const { container, getByTestSubject } = render(
+
+ ({ color: euiTheme.colors.primary })}
+ data-test-subj="consumer"
+ >
+ hello world
+
+
+ );
+
+ expect(getByTestSubject('consumer')).toHaveStyleRule('color', '#07C');
+
+ expect(container.firstChild).toMatchInlineSnapshot(`
+
+ hello world
+
+ `);
+ });
+
+ it("allows consumers to override EUI's ThemeProvider with their own theme", () => {
+ const customTheme = {
+ brandColor: 'pink',
+ };
+
+ const { container, getByTestSubject } = render(
+
+ {/* @ts-ignore - consumers would set their own emotion.d.ts */}
+
+ ({ color: theme.brandColor })}
+ data-test-subj="consumer"
+ >
+ hello
+
+ {/* Custom Emotion themes should not break EUI's own Emotion styles */}
+
+ world
+
+
+
+ );
+
+ expect(getByTestSubject('consumer')).toHaveStyleRule('color', 'pink');
+ expect(getByTestSubject('eui')).toHaveStyleRule('color', '#ba3d76');
+
+ expect(container).toMatchInlineSnapshot(`
+
+
+ hello
+
+
+ world
+
+