Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/im-mou/alias-classname

Easily compose, manage and simplify CSS classes using aliases.
https://github.com/im-mou/alias-classname

alias aliases bem class classname clsx composition css javascript jsx react tailwind web

Last synced: 24 days ago
JSON representation

Easily compose, manage and simplify CSS classes using aliases.

Awesome Lists containing this project

README 

        











alias-classname






















# alias-classname



![Build](https://img.shields.io/github/actions/workflow/status/im-mou/alias-classname/ci.yml?branch=master)

![Test coverage](https://img.shields.io/codecov/c/github/im-mou/alias-classname)

![npm version](https://img.shields.io/npm/v/alias-classname)

![npm license](https://img.shields.io/npm/l/alias-classname)

![Size](https://img.shields.io/badge/dynamic/json?color=blue&label=size&query=$.size.uncompressedSize&url=https://deno.bundlejs.com?q=alias-classname)



A small utility for defining aliases for CSS classes, resolve those aliases in order to generate a final classes string with conditional joining.



## How It Works



The `aliasClassName` function returned by this module serves as the main interface. It allows you to define aliases and resolve classes using the registered aliases. This utility handles the process of alias resolution and concatenation of classes.



## Highlights



- Under 1 kB minified & gzipped

- Typed with TypeScript

- Fully tested

- Zero dependencies



## Installation



To install simply run:



Yarn:



```bash

yarn add alias-classname

```



NPM:



```bash

npm install alias-classname

```



## Usage



1. Import the `aliasClassName` function from the module:



   ```javascript

   import aliasClassName from "alias-classname";

   ```



2. Define your aliases and resolve class names:



   Basic usage:



   ```javascript

   const classes = aliasClassName();



   const classname = classes("css", "base:my-class", "(base)__modifier");

   // outputs: "css my-class my-class__modifier"

   ```



   With default aliases:



   ```javascript

   const classes = aliasClassName("base:component", "mod:container");



   const classname = classes("(base)", "body:(base)__(mod)");

   // outputs: "component component__container"



   const classname2 = classes("(body)--variant");

   // outputs: "component__container--variant"

   ```



   Default aliases can also be composed:



   ```javascript

   const classes = aliasClassName(

     "base:component",

     "mod:(base)__container",

     "var:(mod)--variant"

   );



   const classname = classes("(base)", "(mod)", "(var)");

   // outputs: "component component__container component__container--variant"

   ```



   > You're not required to use the [BEM naming convention](https://getbem.com/naming/). But if you do, it can be really helpful for that use case.



3. Debugging:



   You can access the aliases and classes stores for debugging purposes:



   ```javascript

   const debugInfo = classes.debug();

   console.log(debugInfo.aliases);

   console.log(debugInfo.classes);

   ```



## Problem



When working on projects with complex CSS class naming conventions, managing them can become really cumbersome. Especially when you need to apply multiple classes to elements, the resulting code can quickly become hard to read and maintain.



## Solution



The `aliasClassName` simplifies CSS classes management by allowing you to define aliases for longer class names. These aliases can then be easily used to generate the final joined class names string. This is particularly useful when you want to:



- Maintain cleaner and more readable code by abstracting complex class names behind meaningful aliases.

- Apply consistent and uniform class names throughout your project without repeating lengthy strings.

- Dynamically switch or toggle between different class configurations by using aliases as references.



## Functions and Methods



- `aliasClassName(...aliases: string[]): (classnames: unknown[]) => string`



  This is the main function returned by the module. It takes aliases as arguments and returns a function to resolve class names.



  - `(...classnames: unknown[]): string`



    This is the returned function that takes an array of strings, including aliases, as arguments and returns the resolved final class name string. It concatenates the class names based on the registered aliases.



  - `debug(): { aliases: AliasesStore, classes: ClassesStore }`



    This method is a property attached to the returned function that allows you to retrieve the current state of the aliases and classes stores for debugging purposes.



## Terminology



- **Aliases:** Shorter identifiers that can be used in place of longer class names.



- **Class Names:** CSS class names or any string that you want to resolve and concatenate.



## Limitations and Considerations



- Aliases should be provided as strings in the format:

  - `"alias:class-name"`.

- An alias reference should be provided in the format:

  - `"(alias)__class-name"`.

- An alias must have been registered before it's referenced.

- A redefinition of an existing alias will override its current value.

- Circular references or an alias that doesn't exist are not resolved.

  - `"a:(a)"` will output `"(a)"`.



## Contributing



All contributions are very welcome. You can submit any ideas as [pull requests](https://github.com/im-mou/alias-classname/pulls) or as [GitHub issues](https://github.com/im-mou/alias-classname/issues). If you'd like to improve code, please feel free!