https://github.com/goldenpathtechnologies/tagged-classnames
A utility designed to ease maintenance and organization of Tailwind classes.
https://github.com/goldenpathtechnologies/tagged-classnames
Last synced: 5 months ago
JSON representation
A utility designed to ease maintenance and organization of Tailwind classes.
- Host: GitHub
- URL: https://github.com/goldenpathtechnologies/tagged-classnames
- Owner: goldenpathtechnologies
- License: mit
- Created: 2023-03-17T02:54:07.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2023-10-22T10:36:35.000Z (over 2 years ago)
- Last Synced: 2025-08-04T00:32:20.619Z (11 months ago)
- Language: TypeScript
- Homepage: https://tagged-classnames.goldenpath.ca/
- Size: 467 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# tagged-classnames
A utility designed to ease maintenance and organization of Tailwind classes.
[](https://github.com/goldenpathtechnologies/tagged-classnames/actions/workflows/release.yml)
[](https://github.com/goldenpathtechnologies/tagged-classnames/actions/workflows/docs.yml)
[](https://conventionalcommits.org)
## Demo
See `tagged-classnames` in action [here](https://tagged-classnames.goldenpath.ca/demo/).
## Installation
PNPM:
```bash
pnpm add tagged-classnames
```
NPM:
```bash
npm install tagged-classnames
```
Yarn:
```bash
yarn install tagged-classnames
```
## Usage
### Basic example
Import `tagged-classnames` and use it to make long class lists more maintainable.
```tsx
import tw from "tagged-classnames";
export default function Example() {
return (
Button
);
}
```
The same can be accomplished using only a template literal, however, all whitespace would be retained. This is what
that looks like in the DOM:
```html
Button
```
This is what the same element looks like in the DOM after using `tagged-classnames`:
```html
Button
```
`tagged-classnames` gives you the flexibility template literals offer while keeping the resulting DOM tidy.
### String interpolation
`tagged-classnames` retains the ability to use string interpolation as with plain template literals, but with an
important [caveat](#known-limitations).
```tsx
import tw from "tagged-classnames";
export default function Example({ someCondition }) {
return (
Button
);
}
```
Don't do this:
```jsx
Button
```
The above example will produce `bg-`, `-700`, and one of `blue` or `green` classes. Use whole class names like in
the first string interpolation example if you need to conditionally apply classes.
### Use variables for reusability and cleaner tags
```tsx
import tw from "tagged-classnames";
const buttonStyles = tw`
text-white bg-blue-700 hover:bg-blue-800 focus:ring-4 focus:ring-blue-300
font-medium rounded-lg text-sm px-5 py-2.5 mr-2 mb-2 dark:bg-blue-600
dark:hover:bg-blue-700 focus:outline-none dark:focus:ring-blue-800
`;
export default function Example() {
return (
Button
);
}
```
### Line comments
`tagged-classnames` supports line comments in the tag function's template literal to help document complex style rules.
```tsx
import tw from "tagged-classnames";
export default function Example() {
return (
Button
);
}
```
Comments are not rendered in the DOM and don't affect the formatting of the class list. String interpolation is not
allowed in comments and will throw an error.
Don't do this:
```jsx
Button
```
### Block comments
C-style block comments are also supported. The same string interpolation limitations as with line comments also
applies to block comments.
```tsx
import tw from "tagged-classnames";
export default function Example() {
return (
Button
);
}
```
Additionally, block comments must be properly terminated or an error will be thrown.
```jsx
Button
```
### Performant class list rendering
An alternative function `cx` is available for faster class list rendering if you don't need to use comments.
```tsx
import { cx } from "tagged-classnames";
export default function Example() {
return (
Button
);
}
```
If you're worried about performance, it's a good idea to use `cx` by default, and only use the default function if
you need to comment your classes.
## Functions
### `tw` (default)
Removes excessive whitespace and comments from CSS class lists. Enables flexible formatting of long lists of CSS
classes.
```typescript
function tw(classNames: TemplateStringsArray, ...args: string[]): string {}
```
### `cx`
Removes excessive whitespace from CSS class lists. Does not support comments. More performant than `tw`.
```typescript
function cx(classNames: TemplateStringsArray, ...args: string[]): string {}
```
## Known limitations
- When using string interpolation in the `tagged-classnames` tag function, all interpolated values will be appended
to the end of the class list.
- String interpolation can not be used to construct class names within the tag function. This must be done elsewhere
in the code.
## Issues
Please report any issues with this software
[here](https://github.com/goldenpathtechnologies/tagged-classnames/issues). If you would like to contribute to
this project, feel free to fork it and send a pull request. Note that this project is governed by a
[code of conduct](https://github.com/goldenpathtechnologies/tagged-classnames/blob/main/CODE_OF_CONDUCT.md).
## License
This project is [MIT](https://github.com/goldenpathtechnologies/tagged-classnames/blob/main/LICENSE)
licensed.