Is the language for map design used by Mapbox Studio Classic. It is similar in syntax to CSS, but builds upon it with specific abilities to filter map data and by providing things like variables.
Carto, aka CartoCSS, targets the Mapnik renderer and is able to generate Mapnik XML.
Carto is an evolution of the Cascadenik idea and language, with an emphasis on speed and flexibility. If you are a previous user of Cascadenik, see the key differences wiki.
For users looking to learn how to use Mapbox Studio Classic the best places to start are to 1) Download Mapbox Studio Classic and 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 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('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.
To install, download or clone this repository, then copy the vim-carto
directory located at build/vim-carto to your ~/.vim directory.
cp build/vim-carto/* ~/.vim -R
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 carto receives a total of 428 weekly downloads. As such, carto popularity was classified as not popular.
We found that carto demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers 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
Deno 2.2 enhances Node.js compatibility, improves dependency management, adds OpenTelemetry support, and expands linting and task automation for developers.
Security News
React's CRA deprecation announcement sparked community criticism over framework recommendations, leading to quick updates acknowledging build tools like Vite as valid alternatives.
Security News
Ransomware payment rates hit an all-time low in 2024 as law enforcement crackdowns, stronger defenses, and shifting policies make attacks riskier and less profitable.