Coder Social home page Coder Social logo

satelllte / tailwind-join Goto Github PK

View Code? Open in Web Editor NEW
3.0 0.0 0.0 386 KB

A tiny utility to join Tailwind classes instead of placing them all into a single line.

Home Page: https://www.npmjs.com/package/tailwind-join

License: MIT License

TypeScript 100.00%
classnames clsx tailwind-css tailwindcss tailwindcss-plugin tailwind-join tailwind-merge tw-join

tailwind-join's Introduction

tailwind-join

A tiny utility to join Tailwind classes instead of placing them all into a single line.

import { twJoin } from 'tailwind-join'

twJoin(
  'm-4',
  'px-2 py-1',
  'bg-red-700 hover:bg-red-500',
) // -> 'm-4 px-2 py-1 bg-red-700 hover:bg-red-500'

Install

npm i tailwind-join

Features

Split classes into multiple lines:

twJoin(
  'm-4',                          // spacing
  'border border-red-400',        // borders
  'bg-red-700 hover:bg-red-500',  // colors
) // -> 'm-4 border border-red-400 bg-red-700 hover:bg-red-500'

Show & hide classes conditionally:

twJoin(
  isLarge ? 'm-4' : 'm-2',  // ternary
  isRed && 'bg-red',        // logical conjunction
)

Also:

  • Bundle size is very tiny (less than 300 bytes minified & gzipped). Check out "tailwind-join" on Bundlephobia.
  • TypeScript support.
  • Works in all modern browsers and Node.js@16+.

FAQ

What is the difference between tailwind-join and other utilities like classnames, clsx?

tailwind-join just focuses more on solving the Tailwind classes "hell" issue when tens of classes are placed into a single line. On the other hand, it has even smaller bundle size than classnames and clsx so it can be also intensively used for building classes conditionally using only "ternary" and "logical conjunction" operators approaches described above.

Why not just use multiple lines for classes?

You can, but the HTML output is going to have redundant spaces and line breaks, and tailwind-join takes care of it - so the final HTML output will be always solid:

<div class="m-4 px-2 py-1 bg-black">
  ...
</div>

Can tailwind-join be used for non-Tailwind classes?

Absolutely! tailwind-join doesn't know anything about Tailwind, it only solves the "single line classes" issue.

Is there any plans to expand the API of tailwind-join?

No. The main focus is to solve the "single line classes" issue. Also, the two conditional approaches - "ternary" and "logical conjunction" are also enough. Actually, you can even consider using tailwind-join as the replacement for clsx and classnames with more strict approach for conditionals. In this case they all are going to be written in the same style, without messing around with objects, nested arrays, etc.

Can Tailwind CSS IntelliSense VSCode plugin be used with tailwind-join?

Yes! Just add this to .vscode/settings.json:

{
  "tailwindCSS.experimental.classRegex": [
    ["twJoin\\(([^)]*)\\)", "'([^']*)'"]
  ]
}

Benchmarks

TL;DR

Faster than clsx for the most of practical scenarios.

Details

Since this utility does less job than clsx (no mess around with array & object arguments), it makes sense that twJoin is faster in practice. Though it does worse with a single class argument (most probably because it just uses ES6 (...args) destruction assignment operator to accept arguments instead of using ES5 function's arguments object), it does better on 2 or more arguments.

Here's the benchmark example taken on Linux machine with Node.js v18:

benchmarking: clsx (one class)
	warmup... 82.65ms (10 runs)
	total: 79.17ms, runs: 10 (@ 1000000 calls/iter)
	mean: 7.92ms, median: 7.70ms, range: [7.70..9.64]
	q1: 7.70ms, q3: 7.81ms
	sd: 7.27%
benchmarking: twJoin (one class)
	warmup... 144.26ms (10 runs)
	total: 142.09ms, runs: 10 (@ 1000000 calls/iter)
	mean: 14.21ms, median: 14.09ms, range: [14.07..15.30]
	q1: 14.09ms, q3: 14.10ms
	sd: 2.56%
Fastest: "clsx (one class)"
---
benchmarking: clsx (two classes)
	warmup... 507.90ms (10 runs)
	total: 502.84ms, runs: 10 (@ 1000000 calls/iter)
	mean: 50.28ms, median: 50.26ms, range: [50.15..50.55]
	q1: 50.20ms, q3: 50.40ms
	sd: 0.24%
benchmarking: twJoin (two classes)
	warmup... 461.69ms (10 runs)
	total: 456.70ms, runs: 10 (@ 1000000 calls/iter)
	mean: 45.67ms, median: 45.67ms, range: [45.52..45.86]
	q1: 45.61ms, q3: 45.78ms
	sd: 0.22%
Fastest: "twJoin (two classes)"
---
benchmarking: clsx (many classes)
	warmup... 968.78ms (10 runs)
	total: 915.21ms, runs: 10 (@ 1000000 calls/iter)
	mean: 91.52ms, median: 91.46ms, range: [91.34..91.89]
	q1: 91.43ms, q3: 91.67ms
	sd: 0.18%
benchmarking: twJoin (many classes)
	warmup... 784.45ms (10 runs)
	total: 783.18ms, runs: 10 (@ 1000000 calls/iter)
	mean: 78.32ms, median: 78.32ms, range: [78.20..78.53]
	q1: 78.25ms, q3: 78.46ms
	sd: 0.14%
Fastest: "twJoin (many classes)"

For more benchmark runs see: https://github.com/satelllte/tailwind-join/actions/workflows/benchmark.yml

tailwind-join's People

Contributors

satelllte avatar

Stargazers

 avatar  avatar  avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.