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

Airship Content

Airship is divided into three main packages:

These three packages are what Airship provides to build your own location intelligence application.

Components

Airship components are built on top of StencilJS, which allows us to provide lightweight and easy to use components.

You can find the components’ source code in src/components folder. Each component has several files associated:

  • TSX component file: Main component file where the logic and template is.
  • SASS styles file: Provided component styles.
  • Component Tests file: Unit component tests.
  • Example HTML file: Component showcase showing all the component variants and behaviour.

Airship components are always lazy loaded, so there is no need to worry about importing the whole bundle or each component separately. By importing @carto/airship-components package, the components loader will be included in your bundle and it will lazy-load components by injecting them as soon as they are present in the DOM.

Styles

Airship styles are split into several folders to allow importing the whole bundle or each style separately, aiming to give flexibility and the possibility to reduce the size of the application’s final bundle.

Styles are provided in two different flavours:

  • SASS: Uncompiled styles to process on the build step, allowing you to modify variables and customize Airship styles.
  • CSS: CSS styles to import in your bundle or your HTML directly, avoiding the build step.

We follow the same directory scaffolding in both cases, whether they are SASS styles or CSS styles. The root directory for each flavour is:

  • CSS: @carto/airship-style/dist/{path}
  • SASS: @carto/airship-style/src/{path}

In case you want to import the whole bundle, you need to import:

  • JavaScript: import '@carto/airship-style';
  • CSS: @import '~@carto/airship-style';

If you want to include any of the styles separately, you need to look for the path and append it to the root directory folder. You can find all of them here.

All directories have a similar structure:

  • Style file: the main styles for the component, named like the folder.
  • README.md: a brief explanation of the component and its usage.
  • Test folder: Rendering tests to check component’s requirements.

Whenever you need to import any of those components, include the appropriate snippet in your code:

  • SASS styles:
    • JavaScript import: import '@carto/airship-style/src/{path}';
    • SASS import: @import '~@carto/airship-style/src/{path}';
  • CSS styles:
    • JavaScript import: import '@carto/airship-style/dist/{path}';
    • SASS import: @import '~@carto/airship-style/dist/{path}';

Assuming that you want to import badges component, these are the snippets you can choose from:

  • SASS styles:
    • JavaScript import: import '@carto/airship-style/src/badges/badges';
    • SASS import: @import '~@carto/airship-style/src/badges/badges';
  • CSS styles:
    • JavaScript import: import '@carto/airship-style/dist/badges/badges';
    • SASS import: @import '~@carto/airship-style/dist/badges/badges';

Icons

Airship includes a set of icons to place into your application. These icons can be found in this folder.

Each SVG is automatically generated from a path set in paths.js.

Similarly to styles, we provide icons in two flavours:

  • SVG files: SVG files to include within an <img> tag.
  • Web Font: Icon font containing glyphs to style them with CSS.

While SVG files are easier and lightweight to use, using the Web Font approach provides multiple possibilities for customization with CSS.

When including icons package in CSS or SASS via Webpack or another bundler, it will use Web Font by default. If you prefer to use each SVG file separately, you will need to reference the file via CDN or require the file from node_modules folder wherever you want.

Icons’ dist/ folder is the root content of the npm package. To include each icon separately you need to require the path starting from that folder, like this: @carto/airship-icons/icons/{icon_name}.svg. Replacing {icon_name} with the desired icon name.