Add fallback theme when no ThemeProviders on top

README.md

@@ -12,6 +12,7 @@ yarn add styled-components styled-theming
 
 ## Example
 
+### Without fallback
 ```js
 import React from 'react';
 import styled, {ThemeProvider} from 'styled-components';
@@ -37,6 +38,34 @@ export default function App() {
 }
 ```
 
+### With fallback
+When there is no ThemeProvider on top hierarchy of components, you can set the fallback.
+
+```js
+import React from 'react';
+import styled, {ThemeProvider} from 'styled-components';
+import theme from 'styled-theming';
+
+const boxBackgroundColor = theme('mode', {
+  light: '#fff',
+  dark: '#000',
+}, 'light');
+
+const Box = styled.div`
+  background-color: ${boxBackgroundColor};
+`;
+
+export default function App() {
+  return (
+    <ThemeProvider theme={{ mode: 'light' }}>
+      <Box>
+        Hello World
+      </Box>
+    </ThemeProvider>
+  );
+}
+```
+
 ## API
 
 ### `<ThemeProvider>`
@@ -69,7 +98,7 @@ function App() {
 }
 ```
 
-### `theme(name, values)`
+### `theme(name, values, fallback)`
 
 Most of your theming will be done with this function.
 
@@ -162,7 +191,28 @@ const Box = styled.div`
 `;
 ```
 
-### `theme.variants(name, prop, themes)`
+`fallback` should match one of the keys in your `<ThemeProvider>` theme.
+
+```js
+import styled, { ThemeProvider } from 'styled-components';
+import theme from 'styled-theming';
+
+const backgroundColor = theme('mode', { light: 'lightgray', dark: 'darkgray' }, 'light');
+
+const Button = styled.button`
+  background-color: ${backgroundColor};
+`;
+
+// Example #1 - bg color of this will be lightgray because no ThemeProvider as it's ancestors
+<Button /> 
+
+// Example #2 - bg color of this will be darkgray because it has ThemeProvider with a valid theme prop
+<ThemeProvider theme={{ mode:'dark' }}>
+  <Button />
+</ThemeProvider>
+```
+
+### `theme.variants(name, prop, themes, fallback)`
 
 It's often useful to create variants of the same component that are selected
 via an additional prop.
@@ -171,15 +221,15 @@ To make this easier with theming, styled-theming provides a `theme.variants`
 function.
 
 ```js
-import styled from 'styled-components';
+import styled, { ThemeProvider } from 'styled-components';
 import theme from 'styled-theming';
 
 const backgroundColor = theme.variants('mode', 'variant', {
   default: { light: 'gray', dark: 'darkgray' },
   primary: { light: 'blue', dark: 'darkblue' },
   success: { light: 'green', dark: 'darkgreen' },
   warning: { light: 'orange', dark: 'darkorange' },
-});
+}, 'light');
 
 const Button = styled.button`
   background-color: ${backgroundColor};
@@ -193,8 +243,17 @@ Button.defaultProps = {
   variant: 'default',
 };
 
-<Button/>
-<Button variant="primary"/>
-<Button variant="success"/>
-<Button variant="warning"/>
-```
+// Example #1
+<Button /> // bg color of this will be gray(default - light theme) because no ThemeProvider as it's ancestors
+<Button variant="primary" /> // bg color of this will be blue because no ThemeProvider as it's ancestors
+<Button variant="success"/> // bg color of this will be green because no ThemeProvider as it's ancestors
+<Button variant="warning"/> // bg color of this will be orange because no ThemeProvider as it's ancestors
+
+// Example #2
+<ThemeProvider theme={{ mode:'dark' }}>
+  <Button /> // bg color of this will be darkgray because it has ThemeProvider with a valid theme prop
+  <Button variant="primary" /> // bg color of this will be darkblue because it has ThemeProvider with a valid theme prop
+  <Button variant="success"/> // bg color of this will be darkgreen because it has ThemeProvider with a valid theme prop
+  <Button variant="warning"/> // bg color of this will be darkorange because it has ThemeProvider with a valid theme prop
+</ThemeProvider>
+```

index.js

@@ -6,6 +6,11 @@ function getThemeValue(name, props, values) {
     props.theme[name]
   );
 
+  // Fallback mechanism if there is no theme providers on top hierarchy
+  if (!value) {
+    value = fallback;
+  }
+
   var themeValue;
 
   if (typeof value === 'function') {