https://github.com/chempogonzalez/classname-manager
🖌️ ClassName Manager to easily get classes for component variants
https://github.com/chempogonzalez/classname-manager
classname classnames css manager tailwindcss
Last synced: 3 months ago
JSON representation
🖌️ ClassName Manager to easily get classes for component variants
- Host: GitHub
- URL: https://github.com/chempogonzalez/classname-manager
- Owner: chempogonzalez
- License: mit
- Created: 2022-11-27T23:58:47.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2023-05-30T01:25:06.000Z (about 3 years ago)
- Last Synced: 2025-07-09T10:49:11.089Z (12 months ago)
- Topics: classname, classnames, css, manager, tailwindcss
- Language: TypeScript
- Homepage:
- Size: 120 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 🖌️ classname-manager
[](https://www.npmjs.com/package/classname-manager)
[](https://bundlephobia.com/package/classname-manager@latest)
ClassNames manager to easily get classes for component variants
> Super tiny manager to merge, extend and dynamically add class names focused on variations
>
>
## 🚀 **Features**
- ✅ Super simple and minimalistic
- 🔑 Type-safe (Typescript)
- ❌ No more manual matching classes to props or adding types
- 🧬 TailwindCSS Intellisense support
## 📦 **Install**
```bash
# NPM
npm install classname-manager
# YARN
yarn add classname-manager
# PNPM
pnpm add classname-manager
```
## 💻 **Usage example**
```tsx
import { classNameManager } from 'classname-manager'
interface ButtonProps {
styleType: 'primary' | 'secondary'
color: 'light' | 'dark'
disabled: boolean
}
/**
* Define once the class schema
* based on possible values from props
*
* @example
* - props: { styleType: 'primary', color: 'light' }
* Result: 'btn btn-primary text-black bg-white'
*
*/
const getButtonClassName = classNameManager({
base: 'btn',
dynamicVariants: {
styleType: {
primary: 'btn-primary',
secondary: 'btn-secondary',
},
color: {
light: 'text-black bg-white',
dark: 'text-white bg-black',
},
disabled: {
true: 'btn-disabled bg-gray'
}
}
})
const Button = (props: ButtonProps) => {
const btnClassName = getButtonClassName(props)
return (
{props.label}
)
}
```
## 🧬 TailwindCSS Plugin config _(VSCode)_
In order to allow the tailwindcss plugin intellisense to work properly with `classname-manager` you will need to add the following code to your **`settings.json`** file
```jsonc
// your project > .vscode (folder) > settings.json
{
"tailwindCSS.experimental.classRegex": [
[ "cnm([^ç]*?(base\\:|dynamicVariants\\:)+[^ç]*?)\\}\\);?(\r\n|\r|\n)", "[\"'`]([^\"'`]*).*?[\"'`]" ],
[ "classNameManager([^ç]*?(base\\:|dynamicVariants\\:)+[^ç]*?)\\}\\);?(\r\n|\r|\n)", "[\"'`]([^\"'`]*).*?[\"'`]" ]
]
}
```
---
## 📖 Documentation
The package exports 2 names for the main function, both executes the same:
- `classNameManager`
- `cnm` _(Reduced name)_
### ⭐ Initialization
```tsx
import { cnm } from 'classname-manager'
// By schema object
const getClassName = cnm({ /** Your schema */ })
// By callback returning the schema object
const getClassName = cnm((props) => ({ /** Your schema */ }))
```
### 🔖 SCHEMA object properties
> All schema properties values can be either a string or an array of strings
#### 🟣 `base` _(string | Array\)_
Class to be placed at the beginning of the returned value
```ts
const getClassName = cnm({ base: 'btn', /*...*/ })
// Result: 'btn (other classes)'
```
#### 🟣 `dynamicVariants` _(object)_
Here is where you define your classes based on props passed in to the function.
_(For boolean values the expected properties are: true and false)_
```ts
const getClassName = cnm({
base: 'btn',
dynamicVariants: {
styleType: {
primary: 'btn-primary',
secondary: 'btn-secondary',
},
enabled: {
true: 'bg-transparent',
false: 'bg-gray',
}
}
})
getClassName({ styleType: 'secondary' })
// Result: 'btn btn-secondary'
```
The example above doesn't return any value from the `enabled` property because it's not passed in the function call. You can handle this by adding a `DEFAULT` property to the schema object values
##### - DEFAULT dynamicVariant value
```diff
const getClassName = cnm({
base: 'btn',
dynamicVariants: {
styleType: {
primary: 'btn-primary',
secondary: 'btn-secondary',
},
enabled: {
+ DEFAULT: false,
true: 'bg-transparent',
false: 'bg-gray',
}
}
})
getClassName({ styleType: 'secondary' })
+ // Result: 'btn btn-secondary bg-gray'
```
> **Note:** Although you can use the `DEFAULT` property, it is optional.
In most cases it's recommended to initialize props with a _`default value from js/ts`_ side to have a better control if you need to use it in other places
#### 🟣 `dynamicClassNames` _(object)_
In case you need to apply some logic to calculate if some classes should be added, you can add it like the example below:
```ts
const getClassName = cnm(({ status }) => {
const isDisabled = isButtonDisabled(status)
return {
base: 'btn',
dynamicVariants: {
styleType: {
primary: 'btn-primary',
secondary: 'btn-secondary',
}
},
dynamicClassNames: {
'btn--disabled': isDisabled
}
}
})
// -----------------------------------
getClassName({ status: 'triggered' })
// Result: 'btn btn--disabled'
```
### ⏬ Returned function
When you define your schema, it returns another function that you can use to get the class names based on the props passed in. You can pass an extra property:
#### 🟣 `extraClassNames` _property (string | Array\)_
You can add extra classes to the end of the returned value by using the `extraClassNames` property
```ts
interface ButtonProps {
styleType: 'primary' | 'secondary'
}
const getClassName = cnm({
base: 'btn',
/* your schema */
})
/**
* It allows you to pass extra classes at
* the end of the returned value
*/
getClassName({ styleType: 'primary', extraClassNames: 'font-bold' })
// Result: 'btn btn-primary font-bold'
```
> Created with Typescript! ⚡ and latin music 🎺🎵