Using Cloudscape components

Step 1: Include the Cloudscape Global Styles package

This package contains global styles for Cloudscape components, including the Open Sans font.

1. Install the package by running the following command:

npm install @cloudscape-design/global-styles

2. Include the styles in your application by adding the following import to the main component/page of your application:

import "@cloudscape-design/global-styles/index.css"

Step 2: Install the the React components

1. Install the package by running the following command:

npm install @cloudscape-design/components

2. Import a component by adding the following line of code to your application:

import ComponentName from "@cloudscape-design/components/{component-name}"

For example, to import the button component, add the following line of code to your application:

import Button from "@cloudscape-design/components/button"

After you import the component, you can use it like you would any other React component:

<Button>Hello!</Button>

You can also import components using the following syntax, but this might result in a larger overall bundle size:

import { Button } from "@cloudscape-design/components"

Step 3: Put it all together

import { useState } from "react";
import Header from "@cloudscape-design/components/header";
import Container from "@cloudscape-design/components/container";
import SpaceBetween from "@cloudscape-design/components/space-between";
import Input from "@cloudscape-design/components/input";
import Button from "@cloudscape-design/components/button";

export default function App() {
  const [value, setValue] = useState("");

  return (
    <SpaceBetween size="m">
      <Header variant="h1">Hello World!</Header>

      <Container>
        <SpaceBetween size="s">
          <span>Start editing to see some magic happen</span>
          <Input
            value={value}
            onChange={(event) => setValue(event.detail.value)}
          />
          <Button variant="primary">Click me</Button>
        </SpaceBetween>
      </Container>
    </SpaceBetween>
  );
}

Step 4: View component properties

You can find a full list of components with accompanying documentation on the components page. We use TypeScript definitions to document component properties. If you're using a TypeScript-aware editor, such as VS Code , you can see the full list of components, their available properties, and property types and accepted values with autocomplete or IntelliSense.

Step 5: Integrate with testing libraries

You can configure Cloudscape components to use them alongside testing libraries, such as Jest . For more information, see testing frameworks integration.

Minifying assets with Webpack (optional)

Minifying JavaScript

To achieve the best page loading speed for your web application, we recommend you minify your assets. To do this, you can the mode option in Webpack. Make sure the mode option is set to "production" for your build. This should be enough to minimize your JS assets.

Minifying CSS

By default, CSS assets aren’t minified by Webpack. However, we recommend it for Cloudscape-based applications because our CSS contains comments for documentation purposes, and you’ll want strip them from the production bundle. Install and configure optimize-css-assets-webpack-plugin  in your webpack config by using the following syntax:

// For Webpack v4
const OptimizeCssAssetsPlugin = require('optimize-css-assets-webpack-plugin');

plugins: [new OptimizeCssAssetsPlugin({})]

// For Webpack v5
const CssMinimizerPlugin = require('css-minimizer-webpack-plugin');

optimization: {
  minimize: true,
  minimizer: [new CssMinimizerPlugin()]}

For more information, see the production guide  in the official Webpack documentation.

Bundling CSS

Configuring loaders

When configuring your project, make sure that there are no loaders applied to our content. This is to prevent unintended consequences, including breaking changes:

// sample usage of loaders for your application styles
{
    test: /\.css$/,
    // make sure our content is excluded
    exclude: /node_modules\/@cloudscape-design\//,
    use: [/* your application loaders */]
}

// sample usage of a separate loader for our styles
{
    test: /\.css$/,
    // this may include other third party modules
    include: /node_modules\/@cloudscape-design\//,
    // only these loaders are supported
    use: [MiniCssExtractPlugin.loader, 'css-loader'],
}

Using webpack mini-css-extract-plugin plugin

If you’re using mini-css-extract-plugin , you might get chunk order warnings. These warnings don’t have any impact because Cloudscape component styles are modular and the order of imported styles doesn’t matter. If you want to remove these warnings from the build output, configure the ignoreOrder  property in your webpack configurations to exclude warnings about Cloudscape styles from the output:

ignoreOrder: true

Bundling with Next.js (optional)

If you use Next.js 13 or higher, update your next.config.js file to include the Cloudscape package name in the transpilePackages configuration option:

const nextConfig = {
  transpilePackages: [
    '@cloudscape-design/components',
    '@cloudscape-design/component-toolkit'
  ]
};

module.exports = nextConfig;

If you use an older version of Next.js, use the next-transpile-modules package for the same purpose.