vim-css3-syntax: CSS3 highlighting for Vim, and what it refuses to do

An extension of Vim's CSS syntax, not a replacement

The project is described as CSS3 syntax, and syntax defined in some foreign specifications, support for Vim's built-in syntax/css.vim. That phrasing is the whole design in one line, and it is the difference between this and the other CSS syntax plugins in the wild.

Most syntax plugins work by defining a new syntax file that Vim loads instead of the built in one. This one works with the after mechanism, which is why the repository has an after directory at the root, next to the README and a test directory. An after syntax file does not define a language from scratch, it appends to the groups that the built in file already created, adding the CSS3 keywords, functions and value types to what Vim already knows about CSS.

That is why the README's compatibility section is about the default runtime files rather than about a plugin version. The syntax files are compatible with the default runtime files that come with Vim 9.0 or higher, and the README is explicit that the plugin depends on the built in file being present and current.

The consequence for a user is that the plugin inherits everything Vim already does for CSS and adds to it, rather than replacing it. A bug fixed in Vim's own CSS syntax reaches you without touching this repository, and a divergence in Vim's own file is a divergence in your highlighting too.

The audience is narrow and clear: people who write CSS in Vim and want the newer language constructs coloured, and who are willing to clone a repository and let a plugin extend the runtime.

The primary language of the repository is listed as CSS, which is what you would expect from a project whose payload is CSS vocabulary.

Vim 9 and above, and four instructions for Vim 8 users

The compatibility section is short and unusually specific, and it is worth reading as a list rather than a paragraph.

This syntax files are compatible with the default runtime files that come with Vim 9.0 or higher. If you still use Vim 8.x or lower, the README gives four options.

The first is to copy the latest CSS syntax file to your ~/.vim/ directory, which it marks as recommended. That is Vim's own runtime file, the one linked in the reference list as the upstream css.vim, being placed locally so that your copy is used instead of the one shipped with your Vim.

The second is to update the runtime files, which is the general remedy for a plugin that expects a newer runtime than the one installed.

The third is to use an older version of this plugin, with the reference pointing at the v1.10.2 release, which is the version that still works with the older runtime.

The fourth is to switch to the vim80 branch, a maintained branch in the same repository for users who cannot move to a newer Vim.

Having all four, with one of them marked as the recommended, is the kind of detail that suggests the author has supported a long tail of users. The first option is the interesting one, because it is a manual override of a shipped runtime file, which is invasive enough that the author flags it but considers it the best answer.

The practical point for an evaluator is that the plugin tracks Vim's runtime, not the other way round. If your Vim is old, the question is not which version of this plugin to take but whether you are able to update the runtime, and if not, whether the older release or the branch is acceptable for your use.

The README also points at a manual installation route, which is the third of the three ways to install the plugin and the subject of a later section.

Three installation routes, and which one fits your setup

The installation section covers the three ways people install Vim plugins, and each assumes a different plugin manager.

The Vim package route is the built in one, and it is the shortest:

$ mkdir -p ~/.vim/pack/css3-syntax/start
$ cd ~/.vim/pack/css3-syntax/start
$ git clone https://github.com/hail2u/vim-css3-syntax.git

The pack directory, the start subdirectory and the name of the pack are all significant, because Vim loads everything under a pack's start directory at startup and treats it as a runtime path addition. Naming the pack css3-syntax is what lets the after directory inside the clone be found at the right place in the runtime path, and it is the kind of detail that a copy-paste with a modified directory name will break.

The pathogen.vim route is for people who use that plugin manager, and it is a single clone into the bundle directory:

$ cd ~/.vim/bundle
$ git clone https://github.com/hail2u/vim-css3-syntax.git

The manual route is for everyone else. Download vim-css3-syntax.tar.gz from GitHub, extract it, and copy the contents to your ~/.vim directory.

Note what the manual route implies. Copying the contents means the after directory has to land in the right place inside your runtime path, and if you have several plugins that also extend the built in syntax files, the order in which they are loaded can matter. The package and pathogen routes handle that for you by placing the directory in a location Vim or the plugin manager controls.

So the choice is really about your setup rather than about the plugin. If you use the built in package system, use the pack route. If you use pathogen, use the bundle route. Otherwise, take the tarball and be careful where you put it.

Vendor prefixes, refused on purpose

The first of the two notes is the more interesting, because it is a refusal with a reason attached.

The author does not plan to support CSS3 properties or functions with vendor prefixes, such as -webkit- or -moz-. The reason given is that they are hard to maintain because they are added frequently, changed unexpectedly, and removed silently.

That is a good reason, and it is worth understanding what it means in practice. A prefixed property in a stylesheet is not rare legacy code, it is often the only form the property has in the browser you care about, so a syntax file that does not highlight it produces a file where modern-looking declarations look like errors.

The README does not leave you there. It says these must be supported by separate syntax plugins, and points out that Vim 7.4's default CSS syntax file supports this, which is a slightly confusing sentence to read today given the compatibility requirement is Vim 9, but the substance is that the built in behaviour used to cover prefixed properties and the author has delegated that to other plugins.

For the cases where you want them highlighted without another plugin, the README gives you a way to do it yourself, with two ex commands:

:highlight VendorPrefix guifg=#00ffff gui=bold
:match VendorPrefix /-\(moz\|webkit\|o\|ms\)-[a-zA-Z-]\+/

These commands highlight vendor prefixed properties and functions instantly with cyan and bold, on graphical Vim. The match pattern covers the moz, webkit, o and ms prefixes, which is the historical set, and the character class after the dash is what makes the pattern match a property name rather than a single word.

The trade is explicit: you get a plugin that stays maintainable because it tracks a standard, and you get two lines of configuration if your stylesheets need the non standard forms.

Media Queries, dropped in v0.12.0 and not coming back

The second note is a smaller one but a clearer example of a maintainer drawing a line.

The author drops Media Queries Level 3 support in v0.12.0, and gives the reason: there is no easy way to support Media Queries properly with an after syntax plugin like this one. The apology is in the README, and so is the workaround: if you want to highlight Media Queries correctly, you must update Vim to 8.0 or above.

The technical reason is the interesting part. Media Queries are not a list of keywords added to a language, they are a nested at-rule with their own grammar, and an after syntax file works by adding keywords and match patterns to groups that already exist. Making a nested construct behave properly in that model is genuinely awkward, and the author decided the cost was not worth paying rather than shipping something that half works.

So the plugin's scope is narrower than its name suggests in one direction. It highlights CSS3 properties, functions and value types well, and it declines to model a construct that behaves differently in kind.

This is a good thing to know before installing rather than after, because Media Queries are common in modern stylesheets and the failure mode is silent. The syntax does not error, the media query is simply not coloured the way the rest of the file is.

Taken with the vendor prefix decision, the two notes describe a consistent philosophy. The plugin handles the parts of CSS3 that fit the model of extending a syntax file, and it leaves the parts that need a different kind of grammar to the user or to another plugin.

Cadence, licence and the shape of the repository

The maintenance record is straightforward. The recent releases are v2.11.0 from 2026-08-09, v2.10.0 from 2026-05-09 and v2.9.1 from 2026-02-01, and the last push to the repository was on 2026-10-08. That is a minor release roughly every three months, which is a sensible cadence for a syntax file that has to keep pace with a standard that moves slowly but does move.

The version numbering has also moved past the 0.x line that the README's own history mentions, since it refers to dropping Media Queries in v0.12.0 while the current tags are 2.x. The v1.10.2 release is the one the compatibility section points Vim 8 users at, which tells you how the older line ended.

The licence is MIT, stated in the README's own licence section. The hosting platform records the licence as unknown, which is a discrepancy worth being aware of if your process reads metadata rather than files, and the README is the document that states the terms.

The author is Kyo Nagashima, with the contact address and a personal site in the README, and the repository is tiny: a README, an after directory and a test directory. There is no plugin loader, no configuration file and no build step, which is what a Vim runtime addition should look like.

The test directory is the one entry that says something about rigour. A syntax plugin with a test directory is checking its output, probably against a set of sample files, which is more than most syntax plugins bother with and is what lets the author make claims about which CSS3 constructs are covered.

For an adopter the practical summary is short. Clone it into the right directory for your plugin manager, check whether your stylesheets use Media Queries or prefixed properties, and if they do, decide between the two documented ex commands and a second plugin. Everything else is a git pull.

Editorial conclusion

Adopt vim-css3-syntax if you edit CSS in Vim and the built in syntax file leaves modern properties unhighlighted, since the plugin is a drop-in replacement for syntax/css.vim on Vim 9 and above. Do not adopt it if your stylesheets rely on vendor prefixed properties or on Media Queries, because the author dropped Media Queries Level 3 support in v0.12.0 and deliberately excludes prefixed properties, with a documented workaround for the second case only. Verify first which Vim version you are on, since the syntax files are compatible with the default runtime files of Vim 9.0 or higher and Vim 8 users are pointed at an older release or a separate branch, and that your plugin manager, whether that is the built in package system, pathogen or something else, puts the directory where the after mechanism expects it, because the plugin extends the built in syntax file rather than replacing it.

Frequently asked questions

Official sources

1. hail2u/vim-css3-syntax on GitHub
2. Issues
3. README
4. Releases