react-bootstrap-theme-switcher

A React component to select and switch among Bootstrap (Bootswatch) Themes

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
react-bootstrap-theme-switcher
1.0.77 years ago8 years agoMinified + gzip package size for react-bootstrap-theme-switcher in KB

Readme

react-bootstrap-theme-switcher
A React component for dynamically switching between Bootstrap and Bootswatch themes. Two lines of code and copy themes to your Web server.

A live demo is here
Code for demo here
NOTE: LazyLoader is used to dynamically load stylesheets and re-render after they have been loaded. The theme switcher requires Bootstrap themes and JQuery. Do not load these files either via Webpack or via links in your index.html. Configure the file structure described below (or use the versions included) and the ``ThemeSwitcher`` will automatically load them as needed.

Install

npm install react-bootstrap-theme-switcher

Setup

The theme switcher works by dynamically modifying the document's stylesheet link elements to switch between the default Bootstrap theme or one of the selected Bootswatch themes. There are two components:
A ``ThemeSwitcher`` component that wraps your top-level component. This is responsible for theme loading and hiding your app during the load. A ``ThemeChooser`` component that displays a dropdown button select menu allowing the user to choose a theme.
The ThemeSwitcher will make sure your app is not displayed until the selected theme is loaded, and will also hide it whenever the ThemeChooser selects a new theme. Here is an example of an app that uses the Redux Provider and React Router rendered in index.js:
import { ThemeSwitcher } from 'react-bootstrap-theme-switcher';
const store = configureStore();
const history = syncHistoryWithStore(browserHistory, store);

render(
    <Provider store={store}>
      <ThemeSwitcher themePath="/themes" defaultTheme="yeti">
        <Router history={history} routes={routes} />
      </ThemeSwitcher>
    </Provider>, document.getElementById('app')
);
NOTE: You can wrap any top level component with the ``ThemeSwitcher` *except* for `Provider` (Router or any other component is fine). `Provider` is special, and you'll get a blank screen if you place it inside the `ThemeSwitcher``.
To let users swich themes add the ``ThemeChooser` to one of your pages (e.g. a Settings page). The `ThemeChooser` gets passed a reference to the `ThemeSwitcher` via the `React Context`` mechanism, so it can trigger a re-render and not display the children components during theme unloading and reloading.

ThemeSwitcher props

  • ``themePath`` - location of theme files on server (default '/themes')
  • ``defaultTheme` - default theme to use if user has not selected one (default `'default'``, the Bootstrap theme)
  • ``storeThemeKey` - name of localStorage key used to save the last theme (default `null``)
  • ``themes` - array of themes to display in the `ThemeChooser`` (default is all Bootswatch themes)

Theme files (and required Bootstrap and JQuery javascript)

For convenience the theme switcher comes bundled with the Bootswatch themes, a copy of Bootstrap 3.3.7, and JQuery 3.1.0 located in the themes folder. These files MUST be copied to your distribution folder of your Web server. The structure is:
themes
  /js
    jquery.min.js
    bootstrap.min.js
  /fonts
    ...bootstrap Glyphicon fonts
  /default
    (these two files are the default bootstrap theme)
    bootstrap.min.css
    bootstrap-theme.min.css
  /yeti
    bootstrap.min.css (yeti theme)
  /cerulean
    bootstrap.min.css (cerulean theme)
  other themes    

The theme switcher will add and remove themes by adding and deleting links to the document. For example, if you configure it to locate the themes in '/themes' it will generate links like:
<link rel="stylesheet" type="text/css" href="/themes/default/bootstrap.min.css"
<link rel="stylesheet" type="text/css" href="/themes/default/bootstrap-theme.min.css"

for the default bootstrap theme, or:
<link rel="stylesheet" type="text/css" href="/themes/<themeName>/bootstrap.min.css"

for any of the other themes.
Here is a sample Webpack config that uses the CopyWebpackPlugin to copy the theme files provided with the distribution into your bundle:
import CopyWebpackPlugin from 'copy-webpack-plugin';

export default {
  ...
  plugins: [
    new CopyWebpackPlugin([
        {context: 'node_modules/react-bootstrap-theme-switcher/themes/', from: '**/*', to: 'themes/'}
      ],
      {copyUnmodified: true}
    ),
  ...  

You can use the versions provided by the theme switcher from ``node_modules/react-bootstrap-theme-switcher/themes`` or you generate your own files using different versions of JQuery or Bootstrap. However, the structure and file naming must exactly match what is provided in the distribution. Instructions on downloading/customizing Bootswatch themes can be found here.
NOTE: If you put them in a directory other than ``/themes` you can specify the `themePath` property of the `ThemeSwitcher``.
NOTE: Do NOT load the default Bootstrap theme or JQuery as you might normally do with webpack, e.g. ``require('node_modules/.../bootstrap')`, because the `ThemeSwitcher`` looks for specifically named stylesheet links when removing the current theme. Let the ThemeSwitcher load both Bootstrap and JQuery at startup.

Auto reload last theme used

If you want the last theme used to be automatically loaded in the future you can provide the ThemeSwitcher with the name of a localStorage key to use to save the theme name:
<ThemeSwitcher defaultTheme="yeti" themePath="/themes" storeThemeKey="theme" />
This way, if no theme is currently loaded 'yeti' will be used, but if the user selects another theme it's name will be saved in localStorage under the ``theme`` key and used in the future until it is changed again.

Theme selection

By default the ``ThemeChooser` displays all Bootswatch themes. However, if you only want to use a subset you can specify the theme names via the `themes` property of the `ThemeSwitcher``, for example:
let themes = ['default', 'cerulean', 'darkly'];

render(
    <Provider store={store}>
      <ThemeSwitcher defaultTheme='default' storeThemeKey="theme" themes={themes}>
        <Router history={history} routes={routes} />
      </ThemeSwitcher>
    </Provider>, document.getElementById('app')
);
Make sure that the themes provided include the ``defaultTheme`, if set, and use the lower case theme names. The `ThemeChooser`` will capitalize them and show them in alphabetical order.