styled()

styled() is a custom-built CSS-in-JS utility used to create single-purpose React component styles. This library was inspired by styled-components, Emotion, and CSS Modules.

Foundation

The styled utility is architected similar to styled-components from emotion.sh .

Styled() documentation for building components, changing styles based on a prop, providing CSS resets, and much more!
Additional methods to write CSS

The main way to utilize this tool is to create components using the styled() function like below:


// Button Component
const Button = styled('button')({
  backgroundColor: 'ocean500',
  borderColor: 'ocean500',
  color: 'white',
});
 
// app/index.js
function main() {
  return <Button>Push me</Button>;
}

Styled components

Getting started

Before using the styled() utility, you’ll have to install the following package.


yarn add @activecampaign/camp-core-styled -D
        ```
### Usage
The `styled` utility accepts two arguments to configure a component instance (element and options), followed by an additional function to set component styles
 
```jsx
const Component = styled(element, options)(styles)

The result from the sequence above will point to a new functional component that when rendered will dynamically apply a class selector to the HTML output while adding CSS to the head of the document.

Element


const Component = styled('div')(...)

The first argument represents the component’s element type. Although the above example uses a string to define the type (‘div’), a component (class or function) may be used as an alternate value:


function Section({ children, title, ...props }) {
    return (
        <section {...props}>
        <h2>{title}</h2>
        <div>{children}</div>
        </section>
    );
}
 
export default styled(Section)(...);

Regardless of implementation, the styled utility will forward all unreserved props (review the reserveProps option) to the rendered output. For instance, if we were to create a styled image component:


const Img = styled('img')(...)

All properties (including native HTML attributes) will be forwarded to the rendered markup:


return <Img src="" />;
 
// results in the following HTML
 
<img class="css-..." src="" />;

Options

The second styled utility argument is known as our component options. As illustrated below, a series of configurations can be set to extend the behavior of the rendered component. Possible component options are listed below:


const Component = styled('div', {
    className,
    cssReset,
    reserveProps,
    transformProps
})(...)

Options	Type	Description
`className`	string	This CSS class selector will be prepended and forwarded to the component’s internal className list. This option makes allows you to add a classname to the component. Great for needing a consistent selector for testing, external style overrides, etc.
`cssReset`	object	This provides scoped high level resets. Should contain typical things you’d find in a reset.css file. These resets are easily overridable using any of the methods to add styles.
`reserveProps`	array	List of properties to omit from the rendered component’s prop list. If a property is added to this list, it will not be forwarded as the rendered component. Use this option to avoid invalid HTML attributes being added to native markup during the rendering process.
`transformProps`	object	Configuration object to transform component props to CSS properties. If a transformation results in undefined values, the CSS mapping for such prop will be ignored.

className

Use the className option to add your own class to a component.


// button.tsx
const Button = styled('button',{
    className: 'custom-classname'
})(...)
 
// index.tsx
function Main(){
    return <Button>Press me</Button>
}


<!-- rendered result -->
 
<!-- Note that the className passed PREPENDS -->
<button class="custom-classname css-hki166">Hello, World!</button>

cssReset

Use the cssReset option to add scoped CSS. This should mostly contain high-level CSS reset you’d typically see in a reset.css file.


const Button = styled('button',{
    cssReset: {
        boxSizing: 'content-box',
        fontSize: '200px',
    }
})(...)

reserveProps

transformProps enables the ability to alter the styles of a component based on the props passed in.


// Button.ts
export const Button = styled('button', {
transformProps: {
    // Based on the appearance prop value we can change specific styles
    appearance(value){
    if(value === 'destructive'){
        return {
        backgroundColor: 'strawberry500',
        borderColor: 'strawberry500',
        }
    }
    }
}
})({
// Remember, whatever is passed into this second argument is NOT overridable
backgroundColor: 'ocean500',
borderColor: 'ocean500',
color: 'white',
})(...)

The above component can be used like so:


<Button>Primary Button!!</Button>
<Button appearance="destructive">Destruction Button</Button>
// Boom! You have a primary & destructive button with very little effort!

You can also use transformProps to convert props into CSS values. This is great for creating short hand. See below for example.


// flex.tsx
 
const Flex = styled('div',{
    transformProps: {
    direction: 'flexDirection',
    wrap: 'flexWrap',
    alignItems: null,
    justifyContent: null
    }
})({
display: 'flex'
})

We can now use the Flex component above like this:


<Flex justifyContent='center' alignItems='center' direction='column'>....</Flex>

transformProps

The reserveProps option is required to avoid any props used in transformProps being forwarded to the DOM. Check out the next two code examples below.


// Button.ts
export const Button = styled('button', {
    transformProps: {
        appearance(value){
        if(value === 'destructive'){
            return {
            backgroundColor: 'strawberry500',
            borderColor: 'strawberry500',
            }
        }
    }
}
})({
backgroundColor: 'ocean500',
borderColor: 'ocean500',
color: 'white',
})(...)
 
// index.tsx
function Main(){
    return <Button appearance='primary'>Press Me</Button>
}

The example above will render the following to the DOM:


// 'appearance' is not valid a valid HTML attribute
<button appearance="primary" class="is-styled css-11uj72b">
Press Me!
</button>

Notice that the appearance prop was forwarded to the DOM and is invalid HTML. The reserveProps option solves this problem for us by telling the component what NOT to forward to the DOM.

Let’s fix this this by adding appearance to the reserveProps option.

Note: reserveProps acceps an array of strings so you can pass in multiple props to be omitted from the DOM.


// Button.ts
export const Button = styled('button', {
reserveProps: ['appearance'], //This removes 'appearance' from being fowarded to the DOM
transformProps: {
    appearance(value){
    if(value === 'destructive'){
        return {
        backgroundColor: 'strawberry500',
        borderColor: 'strawberry500',
        }
    }
    }
}
})({
backgroundColor: 'ocean500',
borderColor: 'ocean500',
color: 'white',
})(...)
 
// index.tsx
function Main(){
    return <Button appearance='primary'>Press Me</Button>
}

The code above should render the following:


// That's better! Appearance is no longer forwarded to the DOM and styles still work as expected
<button class="is-styled css-11uj72b">
Press Me!
</button>

Base styles

Since styled is a higher-order function passing in object styles into the second argument will configure component strict styles.

This second argument is special, any styles you pass into here are LOCKED to the component and thus you’re unable to override them easily. (There is an escape hatch called dangerouslySetStyles that we’ll talk more about below).

Note: You can use Design Tokens as values anywhere within styled.


// Button.tsx
const Button = styled('button')({ color: 'ocean500' })
 
// index.tsx
function Main(){
return <Button styles={{color: 'green'}}>Push me</Button>
}
 
 
/**
* In this example the Button font color will resolve to 'ocean500.'
* This behavior is by design. It allows for a contributor to create a component with
* strict styles.
*
*/

What if you want users to be able to pass in some of their own styles?

This can be done a couple different ways. If you want the user to apply some base styles but allow users to override those styles you can use the cssReset option to provide some base styles.


// Button.tsx
const Button = styled('button',{
    cssReset: {
        backgroundColor: 'ocean500'
    }
    })();
 
    ...
 
    // index.tsx
    export default function() {
    return (
        // NOTICE: 'styles' is an inherited prop unique to components created with 'styled'
        // Not to be confused with the `style` html attribute to add inline styles.
        <Button styles={{ backgroundColor: 'banana300' }}>Press me </Button>
    );
}

Using the pattern above allows allows you to set some base styles that are still overridable. Another method is to use the transformProps option above to make more specific prop based styles changes.

Inherited props

As previously mentioned, the styled sequence results in a new functional component, that when rendered, will dynamically add CSS to the head of the document. Aside from the dynamic styles, the following props will be available as part of the component’s API:

`styles` prop

Every component created with styled will have a styles prop giving users the ability to write additional styles along with the ability to pass in design tokens as styles.

Note: styles has an s on the end! This is not the same as the inline style style prop.


// Box.tsx
const Box = styled('div')();
 
// index.tsx
export default function(){
    return (
    <Box
        styles={{
        backgroundColor: 'ocean500', // you can use design tokens as values!
        color: 'green',
        padding: '25px sp600'
        }}
    />
    )
}

`dangerouslySetStyles` prop

This prop is provided as an escape hatch to the styled utility. Every component created using styled() automatically inherits this prop and allows you to over ride ANY styles.

Please proceed with caution. If you are using this prop you are intentionally breaking out of a design system or solving a bug.


    // BlueButton.tsx
    const BlueButton = styled('button')({
        backgroundColor: 'ocean500',
        borderColor: 'ocean500'
    })
    /**
    * The only ways to over ride these values are to use the 'transformProps' option
    * to create an alternate style or use the 'dangerouslySetStyles' component prop
    * like in the example below
    */
 
 
    // index.tsx
    function Main(){
        return (
        <BlueButton
            // now this button will be mint instead of ocean
            dangerouslySetStyles={{
            backgroudColor: 'mint500',
            borderColor: 'mint500'
            }}>
            Push me!
        </BlueButton>
        )
    }

Full prop options

m, string, CSS shorthand for margin
mt, string, CSS shorthand for margin-top
mr, string, CSS shorthand for margin-right
mb, string, CSS shorthand for margin-bottom
ml, string, CSS shorthand for margin-left
mx, string, CSS shorthand for margin-left and margin-right
my, string, CSS shorthand for margin-top and margin-bottom
p, string, CSS shorthand for padding
pt, string, CSS shorthand for padding-top
pr, string, CSS sshorthand for padding-right
pb, string, CSS shorthand for padding-bottom
pl, string, CSS shorthand for padding-left
px, string, CSS shorthand for padding-left and padding-right
py, string, CSS shorthand for padding-top and padding-bottom
styles, object, This prop may be used to write custom CSS for the component. Although these rules will not override internal design system styles, they will take precedence over resets and spacing props
dangerouslySetStyles, object, Similar to the styles prop, this value will create custom CSS rules for the component. However, this prop should be used sparingly as the assigned values will override all previously defined CSS for the component (including design system styles).

Additional methods

Since there are multiple ways to write CSS, the styled utility also supports alternate methods of writing CSS. These alternate methods do NOT create components but instead mainly support writing CSS with the ability to use design tokens as CSS values.

`styled.className()`

If you want to create styles and want to pass them in as a classname you can use this tool to create hashed CSS selectors that dynamically append styles to the head of the document.

Note: Since this tool just created a random classname this tool can be utilized anywhere you can use JS and append the classname.


import styled from '@activecampaign/camp-core-styled';
 
//Create a variable to hold your object styles. Note you can use design tokens and normal css values
const className = styled.className({
    fontSize: 'fs400',
    marginBottom: 'sp500',
    marginTop: '20px'
});
 
export default Title() {
    return (
        // Pass in your variable in any class or className field.
        <h1 className={className}>
        {'Hello, World!'}
        </h1>
    );
}


<!-- rendered result -->
 
<style>
.css-hki166{
    font-size: 18px;
    margin-bottom: 8px;
}
</style>
 
<h1 class="css-hki166">Hello, World!</h1>

`styled.module()`

For those wanting to develop with greater separation of concerns, the styled.module utility can be used to return a series of hashed CSS class selectors:


// header.styles.ts
 
import styled from '@activecampaign/camp-core-styled';
 
// create a variable or default export styled.module with object styles of your choice
export default styled.module({
    container: {
        border: 'bSolid b100 transparent',
        marginBottom: 'sp500',
        ':hover': {
        borderColor: 'slate500'
        }
    },
    title: {
        fontSize: 'fs400',
        marginBottom: 'sp300'
    },
    caption: {
        fontSize: 'fs200'
    }
})


// header.tsx
 
//import your styles
import styles from './header.styles';
 
export default function Header() {
return (
    //Pass in your scoped styles into a components classname
    <div className={styles.container}>
    <h1 className={styles.title}>
        {'Hello, World!'}
    </h1>
    <p className={styles.caption}>
        {'...'}
    </p>
    </div>
);
}


<!-- rendered result -->
 
<style>
.css-gsuqvv{
    border: solid 1px transparent;
    margin-bottom: 16px;
}
.css-gsuqvv:hover{
    border-color: #4E5468;
}
.css-1gekdc9{
    font-size: 18px;
    margin-bottom: 8px;
}
.css-n6y9a7{
    font-size: 14px;
}
</style>
 
<div class="css-gsuqvv">
<h1 class="css-1gekdc9">Hello, World!</h1>
<p class="css-n6y9a7">...</p>
</div>

`styled.settings()`

Not all applications share the same CSS rules, and to accommodate for those differences, styled is equipped with a settings utility to normalize styles for any development environment.

base, number, string, Sets the base rem unit for spacing, type and other px values


import styled from '@activecampaign/camp-core-styled';
 
/**
* The following example will set the internal rem
* unit to 14px. This will convert any token px
* value to use a base of 14px rather than the
* default of 16px.
*/
styled.settings({
    base: '14px'
});

`styled.parseCSS()`

In case there’s a rare need to embed inline styles usng the style HTML attribute or if an application needs to configure third party software using CSS objects, the styled.parseCSS method can be used to convert design tokens to CSS values:

Note: Avoid using inline styles as much as possible


// header.styles.ts
 
import styled from '@activecampaign/camp-core-styled';
 
const css = styled.parseCSS({
    fontSize: 'fs400',
    marginBottom: 'sp300'
});
 
export default function Greeting() {
return (
    <span style={css}>
    {'Hello, World!'}
    </span>
);
}


<!-- rendered result -->
 
<span style="font-size: 18px; margin-bottom: 8px;">
Hello, World!
</span>

Typescript and `styled`

See below for a few best practices for typing your usage of styled

CSS


 
// Camp core typings are available in this package.
import { Core } from '@activecampaign/camp-core-typings';
 
// There are typings specifically for CSS.
export const styles: Core.Styled.CSS = {
color: 'slate600',
...
};

JS


// Camp core typings are available in this package.
import { Core } from '@activecampaign/camp-core-typings';
 
type NewComponentOrientation = 'horizontal' | 'vertical';
 
type NewComponentProps = {
orientation: NewComponentOrientation;
};
 
type NewStyledComponentProps = {
orientation: NewComponentProps;
};
 
// You can extend styled component's styles with your own
const NewStyledComponent: Core.Styled.Component<NewStyledComponentProps> = styled('div', {
transformProps: {
    orientation(value: NewComponentProps['orientation']) {
    return value === 'horizontal'
        ? {
            flexDirection: 'row',
        }
        : {
            flexDirection: 'column',
        };
    },
},
})();