easy-css-merge
v1.0.0
Published
Welcome to easy-css-merge - your streamlined solution for effortlessly merging CSS classes in React, Angular, Vue, or any other JavaScript framework. 🚀
Downloads
363
Maintainers
Readme
easy-css-merge 🌟
Welcome to easy-css-merge - your streamlined solution for effortlessly merging CSS classes in React, Angular, Vue, or any other JavaScript framework. 🚀
easy-css-merge simplifies the process of dynamically adding and managing CSS class names in your JavaScript applications. Whether you're using plain JavaScript, TypeScript, or a popular framework like React or Vue, easy-css-merge enhances your development experience by providing a clean and intuitive API for handling class names.
Seamlessly Manage CSS Classes!
tsCopy code
import merge from 'easy-css-merge';
export const ThemeButton = ({ className }) => {
const [theme, { toggle }] = useTheme();
return (
<button
onClick={toggle}
className={merge('py-3 px-5 font-bold', className, {
'bg-white text-gray-700': theme === 'dark',
'bg-gray-700 text-white': theme === 'light',
})}
>
Toggle theme
</button>
);
};
With easy-css-merge, dynamically adding classes based on state or props becomes straightforward and readable, especially when using utility-first CSS frameworks like Tailwind CSS. LIVE EXAMPLE, CODE
Features of easy-css-merge:
- Simple String Merging: Easily combine class names.
- Array Merging: Combine multiple classes from arrays.
- Object Handling: Apply classes conditionally, similar to Angular's class bindings.
- Filter Functions: Gain advanced control over which classes to include.
Explore the power of easy-css-merge in a Live Example and see how it can simplify your class name management.
Get Started with easy-css-merge
Add easy-css-merge to your project:
npm install easy-css-merge
Then, in your JavaScript or TypeScript files start merging classes!
// merging simple strings
merge('pb-2', 'text-center', 'text-sm'); // 'pb-2 text-center text-sm'
// merging with arrays
merge(['pb-2', 'text-center'], 'text-sm', ['text-lg', 'text-red-500']); // 'pb-2 text-center text-sm text-lg text-red-500'
// merging with objects
merge(
{
'pb-2': true,
'text-center': true,
},
['text-sm text-red-500'],
'text-lg'
); // 'pb-2 text-center text-sm text-red-500 text-lg'
And finally, merging with filters at the end of the merge, or at the end of each group, you can add a filter... With this simple extra step, you can filter out any class you want which give you the ability to override any classes and avoid collisions.
import merge from 'easy-css-merge';
export const ThemeButton = ({ className, classNameFilter }) => {
const [theme, { toggle }] = useTheme();
return (
<button
onClick={toggle}
className={merge(['block py-3 px-5 font-bold', classNameFilter] className, {
'bg-white text-gray-700': theme === 'dark',
'bg-gray-700 text-white': theme === 'light',
})}>
Toggle theme
</button>
);
};
In the previous example, since the classNameFilter is added just to the first group, it will only filter out the classes in that first group; but you can configure this as you want, and add filters at whatever point you want.
The classNameFilter has the following signature:
export type Excludes = string;
export type MergeFilterPredicate = (
value: string,
index: number,
array: string[]
) => boolean;
export type MergeFilter = (() => MergeFilterPredicate) | (() => Excludes[]);
It can be a function that returns a predicate, or an array of strings which will indicate which classes to exclude. In our previous example, if we wanted to exclude the block class, we could do the following:
// By using a filter function
const classNameFilter = () => (key) => key !== 'block';
// By using an array with the classes to exclude
const classNameFilter = () => ['block'];
Usage Examples
Basic Usage:
const className = merge('text-lg', 'font-bold'); // 'text-lg font-bold'
Conditional Classes:
const className = merge({ hidden: isHidden, flex: isFlex }); // 'flex' if isFlex is true
Array and Object Combination:
const className = merge('text-lg font-bold', { hidden: isHidden }); // 'text-lg font-bold' or 'text-lg font-bold hidden' based on isHidden
Advanced Filtering:
const className = merge(
'base',
{ 'text-lg': true, hidden: false },
['p-4', 'm-2'],
() => (cls) => cls !== 'hidden'
); // 'base text-lg p-4 m-2'
Why easy-css-merge?
- Lightweight: No heavy dependencies.
- Flexible: Use in any JavaScript environment.
- Intuitive: Simple API, easy to learn and use.
- Utility-First CSS Friendly: Perfect companion for Tailwind CSS and similar frameworks.
Dive deeper into easy-css-merge on GitHub.
Contribute to easy-css-merge
We welcome contributions! Check out our Contribution Guidelines and join us in enhancing easy-css-merge for developers around the world.
Thanks for reading, hope this help someone