CartoCSS (short: Carto) is a language for map design. It is similar in syntax to CSS, but builds upon it with specific abilities to filter map data and by providing things like variables. It targets the Mapnik renderer and is able to generate Mapnik XML. It can run from the command line or in the browser.
Carto is an evolution of the Cascadenik idea and language, with an emphasis on speed and flexibility.
This project is a fork of Mapbox' original CartoCSS implementation.
The best place to start is to review the Carto reference documentation.
Tutorials like the Mapbox Getting started with CartoCSS guide are a great place to start to learn the basics of CartoCSS.
For more advanced topics see the Studio style quickstart guide and Studio style manual. The links below reference the Tilemill application, which preceded Mapbox Studio Classic, but still contain useful and relevant information.
For details about how to install Carto from source and use on the command line see the Installation section.
In CSS, a certain object can only have one instance of a property. A <div> has a specific border width and color, rules that match better than others (#id instead of .class) override previous definitions. CartoCSS acts the same way normally for the sake of familiarity and organization, but Mapnik itself is more powerful.
Layers in Mapnik can have multiple borders and multiple copies of other attributes. This ability is useful in drawing line outlines, like in the case of road borders or 'glow' effects around coasts. CartoCSS makes this accessible by allowing attachments to styles:
#world {
line-color: #fff;
line-width: 3;
}
#world::outline {
line-color: #000;
line-width: 6;
}
Attachments are optional.
While attachments allow creating implicit "layers" with the same data, using instances allows you to create multiple symbolizers in the same style/layer:
#roads {
casing/line-width: 6;
casing/line-color: #333;
line-width: 4;
line-color: #666;
}
This makes Mapnik first draw the line of color #333 with a width of 6, and then immediately afterwards, it draws the same line again with width 4 and color #666. Contrast that to attachments: Mapnik would first draw all casings before proceeding to the actual lines.
CartoCSS inherits from its basis in less.js some new features in CSS. One can define variables in stylesheets, and use expressions to modify them.
@mybackground: #2B4D2D;
Map {
background-color: @mybackground
}
#world {
polygon-fill: @mybackground + #222;
line-color: darken(@mybackground, 10%);
}
CartoCSS also inherits nesting of rules from less.js.
/* Applies to all layers with .land class */
.land {
line-color: #ccc;
line-width: 0.5;
polygon-fill: #eee;
/* Applies to #lakes.land */
#lakes {
polygon-fill: #000;
}
}
This can be a convenient way to group style changes by zoom level:
[zoom > 1] {
/* Applies to all layers at zoom > 1 */
polygon-gamma: 0.3;
#world {
polygon-fill: #323;
}
#lakes {
polygon-fill: #144;
}
}
By defining multiple fonts in a text-face-name definition, you create FontSets in CartoCSS. These are useful for supporting multiple character sets and fallback fonts for distributed styles.
| carto | XML |
|---|---|
text-name: "[NAME]"; text-size: 11; text-face-name: "Georgia Regular", "Arial Italic"; } |
<FontSet name="fontset-0">
<Font face-name="Georgia Regular"/>
<Font face-name="Arial Italic"/>
</FontSet>
<Style name="world-text">
<Rule>
<TextSymbolizer fontset-name="fontset-0"
size="11"
name="[NAME]"/>
</Rule>
</Style>
|
CartoCSS supports a variety of filter styles:
Numeric comparisons:
#world[population > 100]
#world[population < 100]
#world[population >= 100]
#world[population <= 100]
General comparisons:
#world[population = 100]
#world[population != 100]
String comparisons:
/* a regular expression over name */
#world[name =~ "A.*"]
If you're using Mapbox Studio Classic, you're already using CartoCSS and don't need to do a thing.
If you're a developer-type and want to use the carto binary with
node.js (and you have npm installed),
npm install -g @mapbox/carto
Optionally you may also want to install millstone which is required for resolving data in the same way as Mapbox Studio Classic does:
npm install -g millstone
Having millstone installed specifically enable support for localizing external resources (URLs and local files) referenced in your mml file, and detecting projections (using node-srs)
Now that Carto is installed you should have a carto command line tool available that can be run on a Mapbox Studio Classic project:
carto project.mml > mapnik.xml
Available parameters:
Currently CartoCSS is designed to be invoked from node.js.
The Renderer interface is the main API for developers, and it takes an MML file as a string as input.
// defined variables:
// - input (the name or identifier of the file being parsed)
var carto = require('@mapbox/carto');
try {
var data = fs.readFileSync(input, 'utf-8');
var mml = new carto.MML();
mml.load(path.dirname(input), data, function (err, data) {
if (err) throw err;
var output = new carto.Renderer({
filename: input,
local_data_dir: path.dirname(input),
}).render(data);
console.log(output);
});
} catch(err) {
if (Array.isArray(err)) {
err.forEach(function(e) {
carto.writeError(e, options);
});
} else { throw err; }
}
If you want to use CartoCSS within the browser you should not use MML loading via carto.MML.load.
Instead you should supply the JSON of the MML including the Stylesheet strings directly to carto.Renderer.render.
CartoCSS is based on less.js, a CSS compiler written by Alexis Sellier.
See also a list of dependencies.
FAQs
Mapnik Stylesheet Compiler
The npm package alacarto receives a total of 1 weekly downloads. As such, alacarto popularity was classified as not popular.
We found that alacarto demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Critics call the Node.js EOL CVE a misuse of the system, sparking debate over CVE standards and the growing noise in vulnerability databases.
Security News
cURL and Go security teams are publicly rejecting CVSS as flawed for assessing vulnerabilities and are calling for more accurate, context-aware approaches.
Security News
Bun 1.2 enhances its JavaScript runtime with 90% Node.js compatibility, built-in S3 and Postgres support, HTML Imports, and faster, cloud-first performance.