[!IMPORTANT] This plugin is a community project and is NOT officialy supported by Tailwind Labs.

tailwind-tools.nvim

Unofficial Tailwind CSS integration and tooling for Neovim using the built-in LSP client and treesitter, inspired by the official Visual Studio Code extension.

Contents

• Features
• Prerequisites
• Installation
• Configuration
• Commands
• Utilities
• Extension
• Related projects
• Contributing

Features

The plugin works with all languages inheriting from html, css and tsx treesitter grammars (php, astro, vue, svelte, ...) and provides the following features:

• Class color hints
• Class concealing
• Class sorting (without prettier-plugin)
• Completion utilities (using nvim-cmp)
• Class motions

[!NOTE] Language services like autocompletion, diagnostics and hover are already provided by tailwindcss-language-server.

Prerequisites

• Neovim v0.9 or higher (v0.10 is recommended)
• tailwindcss-language-server >= v0.0.14 (can be installed using Mason)
• html, css, tsx and your other languages treesitter grammars (using nvim-treesitter)

[!TIP] If you are not familiar with neovim LSP ecosystem check out nvim-lspconfig to learn how to setup the LSP.

Installation

Using lazy.nvim:

-- tailwind-tools.lua
return {
  "luckasRanarison/tailwind-tools.nvim",
  dependencies = { "nvim-treesitter/nvim-treesitter" },
  opts = {} -- your configuration
}

If you are using other package managers you need to call setup:

require("tailwind-tools").setup({
  -- your configuration
})

Configuration

[!IMPORTANT] Neovim v0.10 is required for vscode-like inline color hints.

Here is the default configuration:

---@type TailwindTools.Option
{
  document_color = {
    enabled = true, -- can be toggled by commands
    kind = "inline", -- "inline" | "foreground" | "background"
    inline_symbol = "󰝤 ", -- only used in inline mode
    debounce = 200, -- in milliseconds, only applied in insert mode
  },
  conceal = {
    enabled = false, -- can be toggled by commands
    min_length = nil, -- only conceal classes exceeding the provided length
    symbol = "󱏿", -- only a single character is allowed
    highlight = { -- extmark highlight options, see :h 'highlight'
      fg = "#38BDF8",
    },
  },
  custom_filetypes = {} -- see the extension section to learn how it works
}

Commands

Available commands:

• TailwindConcealEnable: enables conceal for all buffers.
• TailwindConcealDisable: disables conceal.
• TailwindConcealToggle: toggles conceal.
• TailwindColorEnable: enables color hints for all buffers.
• TailwindColorDisable: disables color hints.
• TailwindColorToggle: toggles color hints.
• TailwindSort: sorts all classes in the current buffer.
• TailwindSortSelection: sorts selected classes in visual mode.
• TailwindNextClass: moves the cursor to the nearest next class node.
• TailwindPrevClass: moves the cursor to the nearest previous class node.

Utilities

Utility function for highlighting colors in nvim-cmp using lspkind.nvim:

-- nvim-cmp.lua
return {
  "hrsh7th/nvim-cmp",
  dependencies = {
    "luckasRanarison/tailwind-tools.nvim",
    "onsails/lspkind-nvim",
    -- ...
  },
  opts = function()
    return {
      -- ...
      formatting = {
        format = require("lspkind").cmp_format({
          before = require("tailwind-tools.cmp").lspkind_format
        },
      })
    }
  end
},

[!TIP] You can extend it by calling the function and get the returned vim_item, see the nvim-cmp wiki to learn more.

Extension

The plugin basically works with any language as long it has a treesitter parser and a class query. You can check the currently available queries and supported filetypes here, feel free to request other languages support.

But you can also create your own queries! If you are not familiar with treesitter queries you should check out the treesitter query documentation from Neovim or Treesitter.

To add a new filetype you first need to add it to your configuration then the plugin will search for a class.scm file (classexpr) associated to that filetype in your runtimepath. You could use your Neovim configuration folder to store queries in the following way:

~/.config/nvim
.
├── init.lua
├── lua
│   └── ...
└── queries
    └── myfiletype
        └── class.scm

The class.scm file should contain a query used to extract the class values for a given filetype. The class value should be captured using @tailwind as shown in the follwing example:

; queries/myfiletype/class.scm
(attribute
  (attribute_name) @_attribute_name
  (#eq? @_attribute_name "class")
  (quoted_attribute_value
    (attribute_value) @tailwind))

[!NOTE] Some class ranges cannot be precisely captured using queries alone and are handled in code. You can also check out the existing queries to see more examples.

Related projects

Here are some related projects:

• tailwindcss-intellisense (official vscode extension)
• tailwind-sorter.nvim (uses external scripts)
• tailwind-fold (vscode extension)
• tailwind-fold.nvim
• document-color.nvim (archieved)

Contributing

Read the documentation carefully before submitting any issue.

Feature and pull requests are welcome.