> Read [the intro blogpost][intro-blogpost]
[![Build Status][build-badge]][build]
[![Code Coverage][coverage-badge]][coverage]
[![version][version-badge]][package]
[![downloads][downloads-badge]][npm-stat]
[![MIT License][license-badge]][LICENSE]
[](#contributors)
[![PRs Welcome][prs-badge]][prs]
[![Chat][chat-badge]][chat]
[![Code of Conduct][coc-badge]][coc]
[![Roadmap][roadmap-badge]][roadmap]
[![Examples][examples-badge]][examples]
[![gzip size][gzip-badge]][unpkg-dist]
[![size][size-badge]][unpkg-dist]
[![module formats: umd, cjs, and es][module-formats-badge]][unpkg-dist]
[![Watch on GitHub][github-watch-badge]][github-watch]
[![Star on GitHub][github-star-badge]][github-star]
[![Tweet][twitter-badge]][twitter]
**Table of Contents**
- [The problem](#the-problem)
- [This solution](#this-solution)
- [Installation](#installation)
- [React Native](#react-native)
- [Typescript](#typescript)
- [Video Intro :tv:](#video-intro-tv)
- [Terms and concepts](#terms-and-concepts)
- [glamorous](#glamorous)
- [glamorous API](#glamorous-api)
- [Theming](#theming)
- [Context](#context)
- [Size](#size)
- [Server Side Rendering (SSR)](#server-side-rendering-ssr)
- [Example Style Objects](#example-style-objects)
- [Related projects](#related-projects)
- [Users](#users)
- [Inspiration](#inspiration)
- [Other Solutions](#other-solutions)
- [Support](#support)
- [Got Questions?](#got-questions)
- [Swag 👕](#swag-)
- [Contributors](#contributors)
- [LICENSE](#license)
## The problem
You like CSS in JS, but you don't like having to create entire component
functions just for styling purposes. You don't want to give a name to something
that's purely style-related. And it's just kind of annoying to do the
style-creating, `className` assigning, and props-forwarding song and dance.
For example, this is what you have to do with raw `glamor` (or `aphrodite` or
similar for that matter):
```jsx
const styles = glamor.css({
fontSize: 20,
textAlign: 'center',
})
function MyStyledDiv({className = '', ...rest}) {
return (
)
}
```
## This solution
With `glamorous`, that example above looks as simple as this:
```javascript
const MyStyledDiv = glamorous.div({
fontSize: 20,
textAlign: 'center',
})
```
In fact, it's even better, because there are a bunch of features that make
composing these components together really nice!
Oh, and what if you didn't care to give `MyStyledDiv` a name? If you just want
a div that's styled using glamor? You can do that too:
```jsx
const { Div } = glamorous
function App() {
return (
Hello world!
)
}
```
> Try this out in your browser [here](https://codesandbox.io/s/mDLZ1oKn)!
So that's the basics of this solution... Let's get to the details!
## Installation
This module is distributed via [npm][npm] which is bundled with [node][node] and
should be installed as one of your project's `dependencies`:
```
npm install --save glamorous
```
This also depends on `react` and `glamor` so you'll need those in your project
as well (if you don't already have them):
```
npm install --save react glamor
```
> NOTE: If you're using React v15.5 or greater, you'll also need to have
> `prop-types` installed: `npm install --save prop-types`
You can then use one of the module formats:
- `main`: `dist/glamorous.cjs.js` - exports itself as a CommonJS module
- `global`: `dist/glamorous.umd.js` and `dist/glamorous.umd.min.js` - exports
itself as a [umd][umd] module which is consumable in several environments, the
most notable as a global.
- `jsnext:main` and `module`: `dist/glamorous.es.js` - exports itself using the
ES modules specification, you'll need to configure webpack to make use of this
file do this using the [resolve.mainFields][mainFields] property.
The most common use-case is consuming this module via CommonJS:
```javascript
const glamorous = require('glamorous')
const {ThemeProvider} = glamorous
// etc.
```
If you're transpiling (and/or using the `jsnext:main`):
```javascript
import glamorous, {ThemeProvider} from 'glamorous'
// you can also import specific Glamorous Components (see section below on "Built-in" components)
import {Div, H2} from 'glamorous'
// tags with the same name as built-in JavaScript objects are importable with a Tag suffix
// and tag names that contain dashes are transformed to CamelCase
import {MapTag, ColorProfile} from 'glamorous'
```
If you want to use the global:
```html
```
### React Native
`glamorous` offers a version for React Native projects called `glamorous-native`.
```js
npm install glamorous-native --save
```
You can learn more at the [glamorous-native project][glamorous-native].
### Typescript
`glamorous` includes typescript definition files.
For usage notes and known issues see [other/TYPESCRIPT_USAGE.md][typescript-usage].
## Video Intro :tv:
## Terms and concepts
### glamorous
The `glamorous` function is the main (only) export. It allows you to create
glamorous components that render the styles to the component you give it. This
is done by forwarding a `className` prop to the component you tell it to render.
But before we get into how you wrap custom components, let's talk about the
built-in DOM components.
#### built-in DOM component factories
For every DOM element, there is an associated `glamorous` component factory
attached to the `glamorous` function. As above, you can access these factories
like so: `glamorous.div`, `glamorous.a`, `glamorous.article`, etc.
```jsx
const MyStyledSection = glamorous.section({ margin: 1 })
content
// rendered output: content
// styles applied: {margin: 1}
```
#### glamorousComponentFactory
Whether you create one yourself or use one of the built-in ones mentioned above,
each `glamorousComponentFactory` allows you to invoke it with styles and it
returns you a new component which will have those styles applied when it's
rendered. This is accomplished by generating a `className` for the styles you
give and forwarding that `className` onto the rendered element. So if you're
wrapping a component you intend to style, you'll need to make sure you accept
the `className` as a prop and apply it to where you want the styles applied in
your custom component (normally the root element).
```jsx
const UnstyledComp = ({ className, children }) =>
// styles applied:
// {
// margin: 1px;
// }
```
##### ...styles
The `glamorousComponentFactory` accepts any number of style object arguments.
These can be style objects or functions which are invoked with `props` on every
render and return style objects. To learn more about what these style objects
can look like, please take a look at the [`glamor`][glamor] documentation.
```jsx
const MyStyledDiv = glamorous.div(
{
margin: 1,
},
(props) => ({
padding: props.noPadding ? 0 : 4,
})
)
// styles applied: { margin: 1px; padding: 4px; }
// styles applied: { margin: 1px; padding: 0; }
```
> Tip: glamorous simply takes these style objects and forwards them to `glamor`.
> `glamor` will then merge those together in a way you would expect. One neat
> thing you can do is specify an array of style objects and `glamor` will treat
> that exactly the same. It's really expressive! See the [examples][examples]
> for an example of how this works.
You can also specify other classes you'd like applied to the component as well.
If these classes are generated by glamor, then their styles will be merged with
the glamor style's, otherwise the class name will simply be forwarded. For
example:
```jsx
const className1 = glamor.css({paddingTop: 1, paddingRight: 1}).toString()
const styles2 = {paddingRight: 2, paddingBottom: 2}
const className3 = glamor.css({paddingBottom: 3, paddingLeft: 3}).toString()
const styles4 = {paddingLeft: 4}
const styles5 = props => (props.active ? 'active' : 'not-active')
const MyStyledDiv = glamorous.div(
className1,
styles2,
className3,
styles4,
styles5,
'extra-thing',
)
// styles applied: { padding-top: 1px; padding-right: 2px; padding-bottom: 3px; padding-left: 4px } + 'not-active' and anything coming from `extra-thing`.
```
#### GlamorousComponent
The `GlamorousComponent` is what is returned from the `glamorousComponentFactory`.
Its job is to get all the styles together, get a `className` (from [`glamor`][glamor])
and forward that on to your component.
##### supported props
By default `GlamorousComponent` supports three props: `className`, `css` and `theme`
which are used to override the styles of the component in different scenarios. For a
more detailed explanation see [Overriding component styles](#overriding-component-styles) and [Theming](#theming) sections below.
##### `innerRef`
This is a function and if provided, will be called with the inner element's
reference.
```jsx
const MyDiv = glamorous.div({ padding: 20 })
// You can get a reference to the inner element with the `innerRef` prop
class MyComponent extends React.Component {
render () {
return (
this._divRef = c} />
)
}
}
```
##### other props
Only props that are safe to forward to the specific `element` (ie. that will
ultimately be rendered) will be forwarded. So this is totally legit:
```jsx
```
A use case for doing something like this would be for dynamic styles:
```javascript
const staticStyles = {color: 'green'}
const dynamicStyles = props => ({fontSize: props.size === 'big' ? 32 : 24})
const MyDynamicallyStyledDiv = glamorous.div(staticStyles, dynamicStyles)
```
> The exception to this prop forwarding is the pre-created `GlamorousComponent`s
> (see below).
#### built-in GlamorousComponents
Often you want to style something without actually giving it a name (because
naming things is hard). So glamorous also exposes a pre-created
`GlamorousComponent` for each DOM node type which makes this reasonable to do:
```jsx
const { Div, Span, A, Img } = glamorous
function MyUserInterface({name, tagline, imageUrl, homepage, size}) {
const nameSize = size
const taglineSize = size * 0.5
return (
)
}
```
> Try this out in your browser [here](https://codesandbox.io/s/wmRo8OKDm)!
Having to name all of that stuff could be tedious, so having these pre-built
components is handy. The other handy bit here is that the props _are_ the styles
for these components. Notice that glamorous can distinguish between props that
are for styling and those that are have semantic meaning (like with the `Img`
and `A` components which make use of `src` and `href` props).
The `css` prop can be used to provide styles as an object.
```jsx harmony
import glamorous, {withTheme} from 'glamorous'
const { Div, Span } = glamorous
const predefinedStyle = {
color: '#767676',
fontSize: 18,
}
const MyUserInterface = withTheme(function ({tagline, theme}) {
return (
{tagline}
)
})
```
One other tip... This totally works:
```jsx
JSX is pretty wild!
```
#### Overriding component styles
The most common scenario for using props is to override the style of an
existing component (generated by `glamorous` or not). That can be achieved
by using the props `className`, `css` and `theme` or simply component
composition with the `glamorous()` function.
If you're interested in knowing more about using the `theme` prop, see the
[Theming](#theming) section instead for a more detailed explanation. In this
section we'll explain how to use `className`, `css` and composition to override
the styles of a component.
Let's see how that can be done in the examples below.
> Try this out in your browser [here](https://codesandbox.io/s/Kro5369wG)!
We'll use this as our `GlamorousComponent`:
```javascript
const MyStyledDiv = glamorous.div({margin: 1, fontSize: 1, padding: 1})
```
##### using `className`
For each `className` you provide, the `GlamorousComponent` will check to see
whether it is a [`glamor`][glamor] generated `className` (can be from raw glamor
or from `glamorous`, doesn't matter). If it is, it will get the original styles
that were used to generate that `className` and merge those with the styles for
the element that's rendered in a way that the provided `className`'s styles win
in the event of a conflict.
If the `className` is not generated by `glamor`, then it will simply be
forwarded along with the `GlamorousComponent`-generated `className`.
```jsx
const myCustomGlamorStyles = glamor.css({fontSize: 2})
// styles applied:
// {margin: 1, fontSize: 2, padding: 1}
// as well as any styles custom-class applies
```
##### using `css`
This can be the same type as any of the styles provided
(as in `glamorous.div(...styles)`). If specified, it will be merged with this
component's styles and take highest priority over the component's predefined
styles.
```jsx
const myCustomGlamorStyles = glamor.css({fontSize: 2, padding: 2})
// styles applied:
// { margin: 1px; fontSize: 2px; padding: 3px }
// as well as any styles custom-class applies
```
##### using `glamorous()` composition
If we just want to extend the styles of an existing component it can be done
by using the `glamorous()` function.
```jsx
const MyComposedStyledDiv = glamorous(MyStyledDiv)({fontSize: 4, padding: 4})
// styles applied:
// { margin: 1px; fontSize: 4px; padding: 4px; }
```
In fact, the built-in DOM component factories provided are just an abstraction
of this function, so `glamorous.div` could be written as `glamorous('div')` instead.
### glamorous API
The `glamorous` function allows you to create your own
`glamorousComponentFactory` (see [above](#glamorouscomponentfactory)) for any
component you have. For [example](https://codesandbox.io/s/g5kDAyB9):
```jsx
const MyComponent = props =>
const myGlamorousComponentFactory = glamorous(MyComponent)
const MyGlamorousComponent = myGlamorousComponentFactory({/* styles */})
```
You can also provide a few options to help glamorous know how to handle your
component:
#### displayName
The `displayName` of a React component is used by React in the
[React DevTools][react-devtools] and is really handy for debugging React
applications. Glamorous will do its best to give a good `displayName` for your
component, but, for the example above, the best it can do is:
`glamorous(MyComponent)`. If you want to specify a `displayName`, you can do
so with this property. For [example](https://codesandbox.io/s/P3Lyw5j2):
```jsx
const MyComponent = props =>
const myGlamorousComponentFactory = glamorous(
MyComponent,
{displayName: 'MyGlamorousComponent'}
)
```
> Note: the `displayName` can also included in the className that your
> components are given which makes the development experience a bit nicer.
> To enable this see the section about `config`.
> This will likely be enabled by default in the next major change.
And now all components created by the `myGlamorousComponentFactory` will have
the `displayName` of `MyGlamorousComponent`.
There is also a [babel plugin][babel-displayname] that can monkey-patch the `displayName` onto
the components that you create from your component factory.
#### rootEl
React has an [Unknown Prop Warning][unknown-prop-warning] that it logs when you
pass spurious props to DOM elements: (i.e. ``). Because you
can style your components using props, glamorous needs to filter out the props
you pass so it doesn't forward these on to the underlying DOM element. However,
if you create your own factory using a custom component, glamorous will just
forward all the props (because the component may actually need them and
glamorous has no way of knowing). But in some cases, the component may be
spreading all of the props onto the root element that it renders. For these
cases, you can tell glamorous which element is being rendered and glamorous will
apply the same logic for which props to forward that it does for the built-in
factories. For [example](https://codesandbox.io/s/P18oV4kD2):
```jsx
const MyComponent = props =>
const myGlamorousComponentFactory = glamorous(
MyComponent,
{rootEl: 'div'}
)
const MyGlamorousComponent = myGlamorousComponentFactory(props => ({
fontSize: props.big ? 36 : 24,
}))
// this will render:
//
// with {fontSize: 36}
// `big` is not forwarded to MyComponent because the `rootEl` is a `div` and `big`
// is not a valid attribute for a `div` however `id` will be forwarded because
// `id` is a valid prop
```
#### forwardProps
There are some cases where you're making a `glamorousComponentFactory` out of
a custom component that spreads _some_ of the properties across an underlying
DOM element, but not all of them. In this case you should use `rootEl` to
forward only the right props to be spread on the DOM element, but you can also
use `forwardProps` to specify extra props that should be forwarded. For
[example](https://codesandbox.io/s/GZEo8jOyy):
```jsx
const MyComponent = ({shouldRender, ...rest}) => (
shouldRender ? : null
)
const MyStyledComponent = glamorous(MyComponent, {
forwardProps: ['shouldRender'],
rootEl: 'div',
})(props => ({
fontSize: props.big ? 36 : 24,
}))
// this will render:
//
// with {fontSize: 24}
// `shouldRender` will be forwarded to `MyComponent` because it is included in
// `forwardProps`. `big` will not be forwarded to `MyComponent` because `rootEl`
// is a `div` and that's not a valid prop for a `div`, but it will be used in
// the styles object function that determines the `fontSize`. Finally `id` will
// be forwarded to `MyComponent` because it is a valid prop for a `div`.
```
#### shouldClassNameUpdate
Most of the time, glamor is super fast, but in some scenarios it may be nice to
prevent glamor from computing your styles when you know the class name should
not change. In these cases, you can implement `shouldClassNameUpdate`. For
example:
```jsx
const pureDivFactory = glamorous('div', {
shouldClassNameUpdate(props, previousProps, context, previousContext) {
// return `true` to update the classname and
// `false` to skip updating the class name
return true
},
})
const Div = pureDivFactory({marginLeft: 1})
render()
// this will render:
//
// with {marginLeft: 2}
```
Note that this is _not_ the same as `shouldComponentUpdate`. Your component will
still be rerendered. `shouldClassNameUpdate` is only for allowing you to opt-out
of generating the `className` unnecessarily.
#### propsAreCssOverrides
This allows you to use props as CSS. You always have the `css` prop, but
sometimes it's really nice to use just the props as CSS.
```javascript
const MyDiv = glamorous('div', {propsAreCssOverrides: true})({
margin: 1,
fontSize: 1,
})
render()
// renders with margin: 2, fontSize: 1, and fontWeight: bold on hover
```
> You can also compose the built-in components: `glamorous(glamorous.Div)(/* styles */)`
#### withComponent
In some cases you might want to just copy the styles of an already created
glamorous component with a different tag altogether, `withComponent` function
comes in handy then. For example:
```jsx
const Button = glamorous.button({
display: 'inline-block',
color: 'red',
fontSize: '16px',
margin: '16px',
padding: '8px 16px',
border: '1px solid red',
borderRadius: '4px',
});
// We're replacing the
## Terms and concepts
### glamorous
The `glamorous` function is the main (only) export. It allows you to create
glamorous components that render the styles to the component you give it. This
is done by forwarding a `className` prop to the component you tell it to render.
But before we get into how you wrap custom components, let's talk about the
built-in DOM components.
#### built-in DOM component factories
For every DOM element, there is an associated `glamorous` component factory
attached to the `glamorous` function. As above, you can access these factories
like so: `glamorous.div`, `glamorous.a`, `glamorous.article`, etc.
```jsx
const MyStyledSection = glamorous.section({ margin: 1 })