substyle

What is substyle?

The 'substyle' npm package is a utility for styling React components. It allows you to apply styles in a modular and reusable way, making it easier to manage and maintain your styles. 'substyle' provides a way to handle inline styles, CSS modules, and other styling approaches in a consistent manner.

What are substyle's main functionalities?

Inline Styles

This feature allows you to apply inline styles to your React components. The 'useStyles' function is used to create a style object, which can then be spread onto your component.

const { style } = useStyles({ color: 'red' });

const MyComponent = () => (
  <div {...style}>Hello World</div>
);

CSS Modules

This feature allows you to use CSS modules with your React components. The 'useStyles' function is used to create a style object from the imported CSS module, and you can apply specific classes using the style function.

import styles from './MyComponent.module.css';
const { style } = useStyles(styles);

const MyComponent = () => (
  <div {...style('myClass')}>Hello World</div>
);

Theming

This feature allows you to apply themes to your styles. You can define a theme object and use it to create styles that can be applied to your components.

const theme = { primaryColor: 'blue' };
const { style } = useStyles({ color: theme.primaryColor });

const MyComponent = () => (
  <div {...style}>Hello World</div>
);

Other packages similar to substyle

styled-components

Styled-components is a popular library for styling React components using tagged template literals. It allows you to write actual CSS code to style your components. Compared to 'substyle', styled-components offers a more CSS-like syntax and supports features like theming and extending styles.

emotion

Emotion is a performant and flexible CSS-in-JS library. It allows you to style applications quickly with string or object styles. Emotion provides a similar feature set to 'substyle' but with a focus on performance and flexibility, offering both styled components and css utility.

aphrodite

Aphrodite is a library for inline styles that supports media queries and pseudo-selectors. It generates atomic CSS classes to ensure minimal CSS output. Compared to 'substyle', Aphrodite focuses on generating minimal CSS and supports advanced styling features like media queries.

README

substyle

There are a lot of competing styling approaches for React applications, from good old css and css modules to inline styles and css-in-js solutions. How can authors of component libraries make sure that component styles can be seamlessly integrated and customized in any application?

substyle is a simple utility for building universally stylable React components. By using substyle your components will support styling through:

• css (BEM class names)
• css modules
• inline styles (pure and with Radium)
• Aphrodite
• React Style,
• JSS

Installation

npm install --save substyle

Example

Let's create a simple Popover component using substyle:

import substyle from 'substyle'

const Popover = ({ style, children }) => (
  <div {...style}>
    <button {...style('close')}>x</button>
    { children }
  </div>
)

export default substyle(Popover)

That's all there is for making the styles of the container div and the button element customizable by users of the Popover component.

For using css, assign className

// JSX                                        // Rendered HTML

<Popover className="popover">                 // <div class="popover">
  <span>Hello world!</span>                   //   <button class="popover__close">x</button>
</Popover>                                    //   <span>Hello world!</span>
                                              // </div>

For using inline styles, assign style

// JSX                                        // Rendered HTML

<Popover style={{                             // <div style="background: white;">
  background: 'white',                        //   <button style="right: 0;">x</button>
  close: { right: 0 },                        //   <span>Hello world!</span>
}}>                                           // </div>
  <span>Hello world!</span>
</Popover>

How to use it

TODO

Select style for element

Pass selected style to string type elements

Pass selected style to component type elements

Define default styling

Define style modifiers

• based on props, as second arg to defaultStyle
• based on state, by deriving a modified style (recommend hoisting state, e.g., recompose withState)

Organize default styles

• essential styles: co-located with component
• nice example styles/different themes: extra export, css file, or both

API

The default export of the substyle module is a higher-order component for enhancing a React component class by injecting the special ´style´ prop.

substyle(Component) (default export)

Returns an enhanced version of Component which supports style, className, and classNames props and maps them to a single special style prop.

Arguments

• Component (React component)

There is an additional higher-order component creator function that allows to attach default style definitions for the wrapped component:

defaultStyle([defaultStyles], [mapPropsToModifiers])

Returns a version of the substylehigher-order component which is preconfigured to mergedefaultStyles` with user specified style definitions.

Arguments

• defaultStyle (Object | Function) The default style definitions for the component. Also accepts a function mapping component props to an object of default styles.

• mapPropsToModifiers(): modifiers (Function | Object) If specified,

Enhancing a component with the substyle higher-order function injects a function as the style prop. This function has properties assigned to it which are supposed to be passed as props to the root element returned by the component's render function.

style([keys]) (injected prop)

Returns a new style instance with the nested style definitions for the passed key. The return value can be passed as style prop to an element of a substyle-enabled component or spread into the props of a DOM element.

It might seem a bit weird at first to use the spread operator on a function, but a function is also just a JavaScript object which supports setting, getting--and spreading--properties.

The style property on any instance of the style function (style.style) contains only the direct styles

style supports chaining, since the return value of style is another instance of the same function.

Arguments

• key (string | Array | Object) Specifies the key under which to find the nested style definitions. If the component is used with a className prop, a new class name will be derived for the element by appending the key to the base class name.