Airship

Build responsive, mobile-first location intelligence apps on the web with our front-end component library.

This library is still under support but it will not be further developed. We don’t recommend starting new projects with it as it will eventually become deprecated. Instead, learn more about our current CARTO for React library here

Installing Airship

You can install airship-style using npm or downloading it from a CDN.

Airship is composed of 3 packages that can be used independently:

  • airship-styles: A complete CSS framework to build Location Intelligence apps.
  • airship-icons: High quality icons set availiable as svg or web-font.
  • airship-components: Web components for Location Intelligence apps.

Usage from a CDN

The simplest way to use Airship is to load it from CARTO CDN by including the following snippet in the head of your web application.

1
2
3
4
5
6
7
8
9

<head>
  <!-- Include CSS  -->
  <link rel="stylesheet" href="https://libs.cartocdn.com/airship-style/v2.4.1/airship.css">
  <!-- Include Icons -->
  <link rel="stylesheet" href="https://libs.cartocdn.com/airship-icons/v2.4.1/icons.css">
  <!-- Include Web Components -->
  <script type="module" src="https://libs.cartocdn.com/airship-components/v2.4.1/airship/airship.esm.js"></script>
  <script nomodule="" src="https://libs.cartocdn.com/airship-components/v2.4.1/airship/airship.js"></script>
<head>

Usage from NPM

Styles and fonts

Just install our packages and use it as you wish. We recommend to use webpack loaders to inject the styles in your app.

1

npm i @carto/airship-style @carto/airship-icons

Once installed you can just import all the files or only a small subset.

1
2

// Import all styles
import '@carto/airship-styles';

1
2
3

// Import only core styles and tables
import '@carto/airship-style/dist/core/core.css';
import '@carto/airship-style/dist/table/table.css';

Web components

1

npm i @carto/airship-components

You need to call the defineCustomElements function (better in the app entry point) to use the web components from npm.

1
2
3

import { defineCustomElements } from '@carto/airship-components/dist/loader';

defineCustomElements(window);

Using Airship

Using Airship once included in your webpage is very straightforward.

Airship Styles

To use Airship styles, you only need to add CSS classes to your HTML.

For example a simple button can become an Airship button by simply adding the as-btn class.

1

<button class="as-btn"> Button </button>

Airship classes follow BEM conventions, this means that the classes can be of the following types:

  • Block: Standalone entity that is meaningful on its own. (.block)
  • Element: A part of a block that has no standalone meaning and is semantically tied to its block. (.block__element)
  • Modifier: Modifies the block appearance or behavior. (.block--modifier)

The following classes are part of a tabs element:

.as-toolbar-tabs and .as-tabs to generate a tab block. .as-tabs__item to indicate the items and .as-tabs__item--active to highlight the active item.

1
2
3
4
5
6

 <div class="as-toolbar-tabs as-tabs" role="tablist">
    <button role="tab" class="as-tabs__item as-tabs__item--active">MAP</button>
    <button role="tab" class="as-tabs__item">LEFT</button>
    <button role="tab" class="as-tabs__item">RIGHT</button>
    <button role="tab" class="as-tabs__item">PANELS</button>
  </div>

Airship Icons

You can use Airship icons in two different ways.

As web font

To display an icon only a class and an i tag is required.

1

<i class="as-icon as-icon-twitter"></i>

As SVG

There is no need to include the icons.css file when using the icons this way.

Just include the icons from a CDN as regular SVG images.

1

<img src="https://libs.cartocdn.com/airship-icons/v2.4.1/icons/twitter.svg" alt="Twitter logo">

Web components

Web components should be treated as regular HTML Elements.

A web component is just an HTML tag with some attributes that control its behaviour. Simply include the HTML tag, and edit its properties through attributes or through javascript.

For example a range slider

1
2
3
4
5

<as-range-slider id="range-slider"></as-range-slider>
<script>
  const slider = document.querySelector('#range-slider');
  slider.addEventListener('change', event => console.log('New value:', event.detail));
</script>

Basic template

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

<!DOCTYPE html>
<html>
<head>
  <!-- Include CSS elements -->
  <link rel="stylesheet" href="https://libs.cartocdn.com/airship-style/v2.4.1/airship.css">
  <!-- Include icons -->
  <link rel="stylesheet" href="https://libs.cartocdn.com/airship-icons/v2.4.1/icons.css">
  <!-- Include airship components -->
  <script type="module" src="https://libs.cartocdn.com/airship-components/v2.4.1/airship/airship.esm.js"></script>
  <script nomodule="" src="https://libs.cartocdn.com/airship-components/v2.4.1/airship/airship.js"></script>
  <!-- Include CARTO VL -->
  <script src="https://libs.cartocdn.com/carto-vl/v1.4/carto-vl.min.js"></script>
  <!-- Include Mapbox GL JS -->
  <script src="https://api.tiles.mapbox.com/mapbox-gl-js/v0.52.0/mapbox-gl.js"></script>
  <!-- Include Mapbox GL CSS -->
  <link rel="stylesheet" href="https://api.tiles.mapbox.com/mapbox-gl-js/v0.52.0/mapbox-gl.css" />
</head>
<body class="as-app-body">

  <div class="as-app">
    <header class="as-toolbar"></header>
    <nav class="as-tabs"></nav>

    <div class="as-content">
      <aside class="as-sidebar as-sidebar--left"></aside>

      <main class="as-main">
        <div class="as-map-area">
          <div id="map"></div>

          <div class="as-map-panels">
            <div class="as-panel as-panel--top as-panel--right">
              <div class="as-panel__element as-p--32 as-bg--warning"></div>
            </div>
          </div>

        </div>
        <footer class="as-map-footer as-bg--complementary" style="height: 100px;"></footer>
      </main>

      <aside class="as-sidebar as-sidebar--right"></aside>
    </div>
  </div>

  <!-- Basic CARTO-VL MAP -->
  <script>
    const map = new mapboxgl.Map({
      container: 'map',
      style: carto.basemaps.voyager,
      center: [0, 30],
      zoom: 2
    });

  </script>
</body>
</html>

Reducing bundle size

To get a better page speed performance, we suggest you to only include the styles that are being used in your app.

While Airship will automatically inject necessary components as soon as they are inserted in the DOM, you need to specify which CSS elements you want to load in advance. Here’s an example:

1
2
3
4
5
6
7
8
9
10

<head>
  <!-- Always Include core first -->
  <link rel="stylesheet" href="https://libs.cartocdn.com/airship-style/dist/core/core.css">
  <!-- Include the elements used by your app -->
  <link rel="stylesheet" href="https://libs.cartocdn.com/airship-style/dist/button/button.css">
  <link rel="stylesheet" href="https://libs.cartocdn.com/airship-style/dist/table/table.css">
  <link rel="stylesheet" href="https://libs.cartocdn.com/airship-style/dist/tabs/tabs.css">
  <!-- (optional) Include utils at the end -->
  <link rel="stylesheet" href="https://libs.cartocdn.com/airship-style/dist/utilities/utilities.css">
<head>