rofrischmann/fela

# connect

> **Note**: If you're working with React > 16.3, we **highly recommend** using the [useFela](api/react-fela/useFela) hook instead.<br />It's more easy and safe to use and also has the best rendering performance.
> A HoC ([Higher-order Component](https://medium.com/@dan_abramov/mixins-are-dead-long-live-higher-order-components-94a0d2f9e750#.njbld18x8)) that provides the ability to map rendered classes to the component's props using the `styles` key. It is especially useful if we want to style a huge tree of primitive DOM elements e.g. doing basic layouting. This HoC produces a pure component. Behavior by default can be disabled using the configuration parameter.

## Arguments

| Argument | Type                   | Description                                                                                                    |
| -------- | ---------------------- | -------------------------------------------------------------------------------------------------------------- |
| rules    | _Object_ or _Function_ | An object containing named rules or a function that produces such an object based on the props of a component. |
| config   | _Object?_              | An object containing settings to configure Wrapper Component.                                                  |

## Configuration parameters

| Parameter | Type      | Default | Description                                                                         |
| --------- | --------- | ------- | ----------------------------------------------------------------------------------- |
| pure      | _boolean_ | `true`  | A parameter that enables / disables the behavior when the output component is pure. |

## Returns

(_Function_): Component connector that passes the `styles`, `rules` and `theme` props to a component.

## Provided properties

| Property | Type     | Description                                                                  |
| -------- | -------- | ---------------------------------------------------------------------------- |
| styles   | _Object_ | An object containing class names by keys.                                    |
| rules    | _Object_ | An object containing style rules by keys (used for extend inner components). |
| theme    | _Object_ | An object containing the style theme, if provided.                           |

## Imports

```javascript nocopy
import { connect } from 'react-fela'
import { connect } from 'preact-fela'
import { connect } from 'inferno-fela'
```

## Example

```jsx name=Header.js
const Header = ({ title, styles }) => (
  <header className={styles.container}>
    <h1 className={styles.text}>{title}</h1>
  </header>
)

const container = (props) => ({
  textAlign: 'center',
  padding: '20px',
  height: '200px',
})

const text = (props) => ({
  lineHeight: 1.2,
  fontSize: props.size,
  color: props.color,
})

const ConnectedHeader = connect({
  container,
  text,
})(Header)

// Usage
const Usage = <ConnectedHeader title="Hello World" color="red" size="17px" />
```

### Using a Function of Props

```jsx name=Header.js
const Header = ({ title, styles }) => (
  <header className={styles.container}>
    <h1 className={styles.text}>{title}</h1>
  </header>
)

const rules = ({ size, color }) => ({
  container: {
    textAlign: 'center',
    padding: '20px',
    height: '200px',
  },
  text: {
    lineHeight: 1.2,
    fontSize: size,
    color: color,
  },
})

const ConnectedHeader = connect(rules)(Header)

// Usage
const Usage = <ConnectedHeader title="Hello World" color="red" size="17px" />
```

### Disabling Pure Component Behavior

```javascript
const ConnectedHeader = connect(rules, { pure: false })(Header)
```

## Extending Styles

To extend the styles that are injected through the `connect`, there are several ways.

### Extend Property

It's possible to extend component styles with an `extend` prop that can be either an object or a function.

```jsx name=Header.js
const Header = ({ title, styles }) => (
  <header className={styles.container}>
    <h1 className={styles.text}>{title}</h1>
  </header>
)

const rules = ({ size, color }) => ({
  container: {
    textAlign: 'center',
    padding: '20px',
    height: '200px',
  },
  text: {
    lineHeight: 1.2,
    fontSize: size,
    color: color,
  },
})

const ConnectedHeader = connect(rules)(Component)

const extend = ({ bgColor }) => ({
  container: {
    backgroundColor: bgColor,
    padding: '30px',
  },
  text: {
    fontWeight: 700,
  },
})

// Usage
const Usage = (
  <ConnectedHeader
    title="Hello World"
    size="17px"
    color="red"
    bgColor="blue"
    extend={extend}
  />
)
```

## Reconnection Pattern

Instead of directly passing an `extend` object, one can also use the reconnection pattern to achieve the same effect.

```jsx name=Header.js
const Header = ({ title, styles }) => (
  <header className={styles.container}>
    <h1 className={styles.text}>{title}</h1>
  </header>
)

const rules = ({ size, color }) => ({
  container: {
    textAlign: 'center',
    padding: '20px',
    height: '200px',
  },
  text: {
    lineHeight: 1.2,
    fontSize: size,
    color: color,
  },
})

const ConnectedHeader = connect(rules)(Component)

const extend = ({ bgColor }) => ({
  container: {
    backgroundColor: bgColor,
    padding: '30px',
  },
  text: {
    fontWeight: 700,
  },
})

const ExtendedHeader = connect(extend)(ConnectedHeader)

// Usage
const Usage = (
  <ExtendedHeader title="Hello World" size="17px" color="red" bgColor="blue" />
)
```

## Proxying and Rules Property

If you want to proxy the rules for child components, you can use the `rules` property on inside the component. This is also convenient when you do not want to inline the styles that you plan to use for the extension.

```jsx name=Header.js
const Header = ({ title, styles }) => (
  <header className={styles.container}>
    <h1 className={styles.text}>{title}</h1>
  </header>
)

const rules = ({ size, color }) => ({
  container: {
    textAlign: 'center',
    padding: '20px',
    height: '200px',
  },
  text: {
    lineHeight: 1.2,
    fontSize: size,
    color: color,
  },
})

const ConnectedHeader = connect(rules)(Header)

const extend = ({ bgColor }) => ({
  container: {
    backgroundColor: bgColor,
    padding: '30px',
  },
  text: {
    fontWeight: 700,
  },
})

const HeaderProxy = ({ rules }) => (
  <ConnectedHeader size="17px" extend={rules} />
)

const ExtendedHeader = connect(extend)(HeaderProxy)

// Usage
const Usage = <ExtendedHeader title="Hello World" color="red" bgColor="blue" />
```

The injected `rules` property is the resulting multi-rule, which was also used to resolve the `styles` object. It is injected in order to give the parent component the ability to control the styling of the child components on the basis of its own style.

---

## Related

- [Guide - Usage with React](guides/usage-with-react)