Theming

Customize Fluid UI's look to your exact needs.

Creating your theme

All of Fluid's theme options live inside of your fluid.config.js file. To start you can create and change color palettes using the palettes option. Fluid UI comes with a light adddark palette by default, however, you are free to add additional color palettes if you like.

How to apply additional color palettes is explained further below.

Next to the ability to create custom palettes, you also have the ability to create custom color entries besides the ones that are present by default. These custom entries will automatically be converted to css variables and/or utility classes. Fluid UI also comes with a handy utility function mixColors to easily create your color palettes entries.

fluid.config.js

1 
2 
3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
const { mixColors } = require('@infinityfx/fluid/utils');
        
module.exports = {
    theme: {
        palettes: {
            light: { // change a default palette
                primary: mixColors('#22e39f', '#ffffff', 6)
            },
            myCustomPalette: { // or create your own
                primary: ['#22e39f', '#45e6ad', '#60f0bd', '#8cf5d0', '#baf7e2', '#dcfcf1'],
                // The mixColors call below generates the same result as the array above
                myCustomColor: mixColors('#22e39f', '#ffffff', 6),
                ..
            }
        }
    }
}

Tip
Whilst Fluid UI allows you to fully customize your color palettes by hand, we actually recommend using our Themes tool to easily generate beautiful themes in seconds.

Switching themes

Switching between themes is done using the useFluid hook, which can be used to create your own theme toggle.

1 
2 
3 
import { useFluid } from '@infinityfx/fluid/hooks';

const { colorScheme, appliedColorScheme, setColorScheme } = useFluid();

The useFluid hook returns both a colorScheme and an appliedColorScheme value, both of which are string literal types matching the color palette entries defined in your fluid.config.js file.

The difference is that in addition to the defined color palette keys, colorScheme can also have a value of system. As the name implies, this automatically applies either the light or darkcolor palette based on the user's system preference.

Server-side rendering

Fluid UI uses cookies to store a user's theme preference. Because of this, a user's preferred theme is only read an applied upon page load. If, however, your project uses server-side rendering, this could cause a momentary mismatch in applied theme between the server and client. To prevent this it is advised to populate the initialColorScheme prop on your FluidProvider. This can be done by reading the theme preference cookie on the server using theCOLOR_SCHEME_COOKIE variable.

NextJS example

1 
2 
3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
import { COLOR_SCHEME_COOKIE } from '@infinityfx/fluid/utils';
import { FluidProvider } from '@infinityfx/fluid';
import { cookies } from 'next/headers';

export default function RootLayout({ children }: {
    children: React.ReactNode;
}) {
    const cookieStore = await cookies();
    const colorScheme = cookieStore.get(COLOR_SCHEME_COOKIE)?.value;

    return <html>
        <FluidProvider initialColorScheme={colorScheme}>
            <body>
                {children}
            </body>
        </FluidProvider>
    </html>;
}

Advanced use cases

Component styling

Fluid UI allows you to completely alter a component's look using the components config option. It allows you to change, override and add CSS style rules to any Fluid UI component.

It is highly recommended to add a type annotation, so you get autocomplete for the various component CSS selectors in your IDE.

fluid.config.js

1 
2 
3 
4 
5 
6 
7 
8 
9 
10 
/** @type {import('@infinityfx/fluid').FluidConfig} */
module.exports = {
    components: {
        button: {
            '.v__default': {
                outline: 'solid 2px #ef3f3f' // add an outline around the default button variant
            }
        }
    }
}

Per instance styling

In some cases you might want to change the look of a single component instance, without it affecting every other instance of that component throughout your project. This can be done using the cc (custom classes) prop, which is present on every styled Fluid UI component. It allows you to add extra CSS classes to the various elements and states that make up a component.

1 
2 
3 
4 
5 
6 
7 
8 
9 
<Select
    options={[
        { label: 'First option', value: 0 },
        ..
    ]}
    cc={{
        v__default: 'myClass', // add an extra class to the default variant
        placeholder: 'myOtherClass' // add an extra class to the placeholder element
    }} />

Keep in mind that when using this feature to change a CSS property that is already present in the default component styles, you have to account for CSS specificity rules.