About Project Overview Contributing Getting Started Installation Usage Themes Customizing Frameworks React Vue Angular GitHub Light Dark System

Installation

You can load Terra via CDN or by installing it locally. If you’re using a framework, make sure to check out the pages for React, Vue, and Angular for additional information.

CDN Installation (Easiest)

Autoloader Traditional Loader

The experimental autoloader is the easiest and most efficient way to use Terra. A lightweight script watches the DOM for unregistered Terra elements and lazy loads them for you — even if they’re added dynamically.

While convenient, autoloading may lead to a Flash of Undefined Custom Elements. The linked article describes some ways to alleviate it. 

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@nasa-terra/components@0.0.138/cdn/themes/horizon.css" />
<script type="module" src="https://cdn.jsdelivr.net/npm/@nasa-terra/components@0.0.138/cdn/terra-ui-components-autoloader.js"></script>

The traditional CDN loader registers all Terra elements up front. Note that, if you’re only using a handful of components, it will be much more efficient to stick with the autoloader. However, you can also cherry pick components if you want to load specific ones up front. 

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@nasa-terra/components@0.0.138/cdn/themes/horizon.css" />
<script type="module" src="https://cdn.jsdelivr.net/npm/@nasa-terra/components@0.0.138/cdn/terra-ui-components-autoloader.js" ></script>

Dark Mode

The Horizon theme includes both light and dark modes. Dark mode can be enabled automatically based on system preference by adding the terra-prefers-color-scheme class to the <body> element, or you can manually control it with the terra-theme-dark class. For more details, see the Themes documentation.

Now you can start using Terra!

npm installation

If you don’t want to use the CDN, you can install Terra from npm with the following command.

npm install @nasa-terra/components

It’s up to you to make the source files available to your app. One way to do this is to create a route in your app called /terra-ui-components that serves static files from node_modules/@nasa-terra/components.

Once you’ve done that, add the following tags to your page. Make sure to update href and src so they point to the route you created. 

<link rel="stylesheet" href="/terra-ui-components/dist/themes/horizon.css" />
<script
    type="module"
    src="/terra-ui-components/dist/terra-ui-components.js"
></script>

Alternatively, you can use a bundler.

Setting the Base Path

Some components rely on assets (icons, images, etc.) and Terra needs to know where they’re located. For convenience, Terra will try to auto-detect the correct location based on the script you’ve loaded it from. This assumes assets are colocated with terra-ui-components.js or terra-ui-components-autoloader.js and will “just work” for most users.

However, if you’re cherry picking or bundling Terra, you’ll need to set the base path. You can do this one of two ways. 

<!-- Option 1: the data-terra-ui-components attribute -->
<script
    src="bundle.js"
    data-terra-ui-components="/path/to/terra-ui-components/dist"
></script>

<!-- Option 2: the setBasePath() method -->
<script src="bundle.js"></script>
<script type="module">
    import { setBasePath } from '@nasa-terra/components/dist/utilities/base-path.js'
    setBasePath('/path/to/terra-ui-components/dist')
</script>

Referencing Assets

Most of the magic behind assets is handled internally by Terra, but if you need to reference the base path for any reason, the same module exports a function called getBasePath(). An optional string argument can be passed, allowing you to get the full path to any asset. 

<script type="module">
    import {
        getBasePath,
        setBasePath,
    } from '@nasa-terra/components/dist/utilities/base-path.js'

    setBasePath('/path/to/assets')

    // ...

    // Get the base path, e.g. /path/to/assets
    const basePath = getBasePath()

    // Get the path to an asset, e.g. /path/to/assets/file.ext
    const assetPath = getBasePath('file.ext')
</script>

Cherry Picking

Cherry picking can be done from the CDN or from npm. This approach will load only the components you need up front, while limiting the number of files the browser has to download. The disadvantage is that you need to import each individual component.

Here’s an example that loads only the button component. Again, if you’re not using a module resolver, you’ll need to adjust the path to point to the folder Terra is in. 

<link
    rel="stylesheet"
    href="/path/to/terra-ui-components/dist/themes/horizon.css"
/>

<script
    type="module"
    data-terra-ui-components="/path/to/terra-ui-components/dist"
>
    import '@nasa-terra/components/dist/components/button/button.js'

    // <terra-button> is ready to use!
</script>

You can copy and paste the code to import a component from the “Importing” section of the component’s documentation. Note that some components have dependencies that are automatically imported when you cherry pick. If a component has dependencies, they will be listed in the “Dependencies” section of its docs.

Bundling

Terra is distributed as a collection of standard ES modules that all modern browsers can understand. However, importing a lot of modules can result in a lot of HTTP requests and potentially longer load times. Using a CDN can alleviate this, but some users may wish to further optimize their imports with a bundler.

To use Terra with a bundler, first install Terra along with your bundler of choice.

npm install @nasa-terra/components

Now it’s time to configure your bundler. Configurations vary for each tool, but here are some examples to help you get started.

  • EXAMPLES TBD. Please open an issue if needed

Once your bundler is configured, you’ll be able to import Terra components and utilities.

import ‘@nasa-terra/components/dist/themes/horizon.css’ import ‘@nasa-terra/components/dist/components/button/button.js’ import ‘@nasa-terra/components/dist/components/icon/icon.js’ import ‘@nasa-terra/components/dist/components/input/input.js’ import ‘@nasa-terra/components/dist/components/rating/rating.js’ import { setBasePath } from ‘@nasa-terra/components/dist/utilities/base-path.js’

// Set the base path to the folder you copied Terra’s assets to setBasePath(‘/path/to/terra-ui-components/dist’)

// , , and are ready to use! 


:::warning
Component modules include side effects for registration purposes. Because of this, importing directly from `@nasa-terra/components` may result in a larger bundle size than necessary. For optimal tree shaking, always cherry pick, i.e. import components and utilities from their respective files, as shown above.
:::

### Avoiding auto-registering imports

By default, imports to components will auto-register themselves. This may not be ideal in all cases. To import just the component's class without auto-registering it's tag we can do the following:

```diff
- import TerraButton from '@nasa-terra/components/dist/components/button/button.js';
+ import TerraButton from '@nasa-terra/components/dist/components/button/button.component.js';

Notice how the import ends with .component.js. This is the current convention to convey the import does not register itself.

The difference between CDN and npm

You’ll notice that the CDN links all start with /cdn/<path> and npm imports use /dist/<path>. The /cdn files are bundled separately from the /dist files. The /cdn files come pre-bundled, which means all dependencies are inlined so you do not need to worry about loading additional libraries. The /dist files DO NOT come pre-bundled, allowing your bundler of choice to more efficiently deduplicate dependencies, resulting in smaller bundles and optimal code sharing.

TL;DR:

  • @nasa-terra/components/cdn is for CDN users
  • @nasa-terra/components/dist is for npm users

This change was introduced in v2.5.0 to address issues around installations from npm loading multiple versions of libraries (such as the Lit) that Terra uses internally.