ryan-roemer ESM build, misc other tweaks (#968)
- **Breaking Change**: Radium now exports defaults as `.default`, so for runtimes like Node.js for all files in `lib/**`. We have changed `package.json:main` to point to `/index.js` instead of `/lib/index.js` as a convenience wrapper to expose mostly what was there before so behavior of `const Radium = require('radium');` works mostly as it did before. Caveats:
- Add `es` ESM module export files.
- Fix `package.json:scrtips.postinstall` task to correctly work for git-based dependencies.
Latest commit 0001fcb Feb 9, 2018
Permalink
..
Failed to load latest commit information.
README.md ESM build, misc other tweaks (#968) Feb 9, 2018
upgrade-v0.16.x.md Add upgrade guide for v0.16.x Jan 12, 2016

README.md

Using Radium

Table of Contents

Radium is a toolset for easily writing React component styles. It resolves browser states and media queries to apply the correct styles to your components, all without selectors, specificity, or source order dependence.

How do I do it, then?

First, require or import Radium at the top of component file:

import Radium from 'radium';

// If you want to use the <Style /> component you can do
import Radium, { Style } from 'radium';

Let's create a fictional <Button> component. It will have a set of default styles, will adjust its appearance based on modifiers, and will include hover, focus, and active states.

class Button extends React.Component {
  render() {
    return (
      <button>
        {this.props.children}
      </button>
    );
  }
}

Radium is activated by wrapping your component:

class Button extends React.Component {
  // ...
}
export default Radium(Button);

// or
class Button extends React.Component {
  // ...
}
Button = Radium(Button);

Radium resolves nested style objects into a flat object that can be applied directly to a React element. If you're not familiar with handling inline styles in React, see the React guide to the subject here. A basic style object looks like this:

var baseStyles = {
  background: 'blue',
  border: 0,
  borderRadius: 4,
  color: 'white',
  padding: '1.5em'
};

We usually nest styles inside a shared styles object for easy access:

var styles = {
  base: {
    background: 'blue',
    border: 0,
    borderRadius: 4,
    color: 'white',
    padding: '1.5em'
  }
};

Next, simply pass your styles to the style attribute of an element:

// Inside render
return (
  <button style={styles.base}>
    {this.props.children}
  </button>
);

From there, React will apply our styles to the button element. This is not very exciting. In fact, React does this by default, without the extra step of using Radium. Radium becomes useful when you need to do more complex things, like handling modifiers, states, and media queries. But, even without those complex things, Radium will still merge an array of styles and automatically apply vendor prefixes for you.

Modifiers

Radium provides one shorthand for dealing with styles that are modified by your props or state. You can pass an array of style objects to the style attribute, and they will be merged together intelligently (:hover states, for instance, will merge instead of overwrite). This works the same way as it does in React Native.

<Button
  size="large"
  block={true}>
  Cool Button!
</Button>

Start by adding another style to your styles object:

var styles = {
  base: {
    background: 'blue',
    border: 0,
    borderRadius: 4,
    color: 'white',
    padding: '1.5em'
  },

  block: {
    display: 'block'
  }
};

Then, include that style object in the array passed to the style attribute if the conditions match:

// Inside render
return (
  <button
    style={[
      styles.base,
      this.props.block && styles.block
    ]}>
    {this.props.children}
  </button>
);

Radium will ignore any elements of the array that aren't objects, such as the result of this.props.block && styles.block when this.props.block is false or undefined.

Browser States

Radium supports styling for three browser states that are targeted with pseudo-selectors in normal CSS: :hover, :focus, and :active.

To add styles for these states, add a special key to your style object with the additional rules. Additionally, you will need to add a unique key prop to the elements that take these styles:

var styles = {
  base: {
    background: 'blue',
    border: 0,
    borderRadius: 4,
    color: 'white',
    padding: '1.5em',

    ':hover': {
      backgroundColor: 'red'
    },

    ':focus': {
      backgroundColor: 'green'
    },

    ':active': {
      backgroundColor: 'yellow'
    },
  },

  block: {
    display: 'block',

    ':hover': {
      boxShadow: '0 3px 0 rgba(0,0,0,0.2)'
    }
  },
};

class MyComponent extends Component {
...
render() {
  return (
    <div key="1" style={styles.base}>
      <div key="2" style={styles.block} />
    </div>
  );
}
...
}

export default Radium(MyComponent);

Radium will merge styles for any active states when your component is rendered. If you are having trouble with browser states, check out this section of the FAQ.

Media queries

Add media queries to your style objects the same way as you would add browser state modifiers like :hover. The key must start with @media, and the syntax is identical to CSS:

var style = {
  width: '25%',

  '@media (min-width: 320px)': {
    width: '100%'
  }
};

Radium will apply the correct styles for the currently active media queries. Top level CSS rules in your media queries will be converted to CSS and rendered in an actual <style> element with !important appended instead of being applied inline so they will work with server-side rendering. Note that you must wrap your top-level component in the <StyleRoot> component to render the Radium stylesheet. Print styles will also work as normal, since they are rendered to CSS.

Nested browser states

Media query styles can also contain nested browser states:

var style = {
  width: '25%',

  '@media (min-width: 320px)': {
    width: '100%',

    ':hover': {
      background: 'white'
    }
  }
};

Known issues with media queries

IE9 Support

IE9 supports CSS media queries, but doesn't support the matchMedia API. You'll need a polyfill that includes addListener.

Styling multiple elements in a single component

Radium allows you to style multiple elements in the same component. You just have to give each element that has browser state modifiers like :hover or media queries a unique key or ref attribute:

// Inside render
return (
  <div>
    <div key="one" style={[styles.both, styles.one]} />
    <div key="two" style={[styles.both, styles.two]} />
  </div>
);

var styles = {
  both: {
    background: 'black',
    border: 'solid 1px white',
    height: 100,
    width: 100
  },
  one: {
    ':hover': {
      background: 'blue',
    }
  },
  two: {
    ':hover': {
      background: 'red',
    }
  }
};

Styling one element depending on another's state

You can query Radium's state using Radium.getState. This allows you to style or render one element based on the state of another, e.g. showing a message when a button is hovered.

// Inside render
return (
  <div>
    <button key="keyForButton" style={[styles.button]}>Hover me!</button>
    {Radium.getState(this.state, 'keyForButton', ':hover') ? (
      <span>{' '}Hovering!</span>
    ) : null}
  </div>
);

var styles = {
  button: {
    // Even though we don't have any special styles on the button, we need
    // to add empty :hover styles here to tell Radium to track this element's
    // state.
    ':hover': {}
  }
};

Fallback values

Sometimes you need to provide an additional value for a single CSS property in case the first one isn't applied successfully. Simply pass an array of values, and Radium will test them and apply the first one that works:

var styles = {
  button: {
    background: ['rgba(255, 255, 255, .5)', '#fff']
  }
};

Is equivalent to the following CSS (note that the order is reversed):

.button {
  background: #fff;
  background: rgba(255, 255, 255, .5);
}

<Style> component

Want to add a style selector within your component? Need to pass properties to the html and body elements or group selectors (e.g. h1, h2, h3) that share properties? Radium has you covered with the <Style /> component - read how to use it here.