📘

Before we start

The following guide assumes you have some familiarity with React and JSX concepts. At minimum, it is recommended that you have some experience with JavaScript before continuing with this guide. There are some great free resources available at freecodecamp.org, otherwise continue reading.

Using static classNames

CSS class naming still remains the most effective way to ensure that you can create reusable styles for your various components. By using static className values, you can make styles from campaign editor styles and apply them throughout various parts of your Raisely website:

(RaiselyComponents) => {
    const PrimaryDiv = ({ children }) => (
        <div className="my-primary-div" />
    );

    const SecondaryDiv = ({ children }) => (
        <div className="my-secondary-div" />
    );

    return () => (
        <React.Fragment>
            <PrimaryDiv />
            <SecondaryDiv />
        </React.Fragment>
    );
}

Raisely also provides several css helpers to ensure you can get the most out of your css styles. These helpers include means of styling sections of components based on colors, as well as hiding sections of components depending on page state, like if a profile is owned by the current user, or the page currently in view.

You can find a throughout listing of our helper classes from here

(RaiselyComponents) => {
    // define both our campaign theme color aliases and their available shades
    const colorTypes = [
        'block-primary', 'block-secondary',
        'color-primary', 'color-secondary',
    ];

    const colorShades = [
        'super-light', 'lightest', 'lighter', 'light',
        'dark', 'darker', 'darkest',
    ];

    // generate list of class names for helper demo
    const colorHelperClasses = colorTypes.concat(...colorTypes.map(colorType => 
        colorShades.map(shadeName => `${colorType}-${shadeName}`)
    )).sort();

    // return mapping of available colors as simple div elements
    return () => colorHelperClasses.map(className => (
        <div className={className} key={className}>
            {className}
        </div>
    ));
}

Using Emotion

🚧

This section has been moved (and updated)

You can view the newest emotion helper documentation here

Emotion is a Javascript based dynamic style solution that is used internally by Raisely, and for various aspects of the client.

Emotion's styled and css helpers allow you to build components that aren't as closely dependant on your existing campaign styles, since the HTML class they are assigned is uniquely represented when it's rendered.

This means that unlike typical CSS classes that are more easily targeted, CSS classes and elements made using emotion aren't easily targeted, and wont conflict with other emotion generated classes.

(RaiselyComponents) => {
    const { styled, css } = RaiselyComponents;

    // a HTML div that will have a unique className already assigned
    // to it via styled
    const MyRedDiv = styled('div')`
        color: #fff;
        background: #f00;
    `;

    // builds a reusable string that can be appended as a className
    const myBlueClass = css`
        color: #fff;
        background: #00f;
    `;

    return () => (
        <React.Fragment>
            <MyRedDiv>
                Hi I'm Red!
            </MyRedDiv>
            <div className={myBlueClass}>
                Hi I'm Blue!
            </div>
        </React.Fragment>
    );
}

As demonstrated above, the emotion helpers provide two helpers; styled which enables developers to create components with deterministic styled bound to each element, and css which acts a declarative way to define a set of styles for React components without needing an previously-used CSS class name appended. Both of these helpers provide the means of preventing style conflicts within you other components and existing campaign theme styles.

You can learn more about Emotion's syntax from their v9 documentation

Styling existing Raisely components

A brief introduction to BEM

The majority of Raisely's donor-facing client employs a CSS naming standard called BEM, which enables a highly declarative and transparent way to describe component styles and hierarchies in a one-dimensional pattern.

We chose this for the main intent of ensuring that client-side styles are easily customisable and adaptable depending on the stylistic choices of your own campaign.

Here's a few consolidated resources that are great for getting to know BEM on a fundamental level:

• https://css-tricks.com/bem-101/
• https://codeburst.io/understanding-css-bem-naming-convention-a8cca116d252
• https://github.com/airbnb/css

Sometime in the future, we'll release a more in-depth guide to applying BEM in a way specific to Raisely and how to take advantage of more advanced theming practices.