Cloudscape Design System
  • Get started
  • Foundation
  • Components
  • Patterns
  • Demos
  • GitHub 
Cloudscape Design System
  • Get started
  • Foundation
  • Components
  • Patterns
  • Demos
  • GitHub 
  • About
  • Guides
    • Introduction
    • Get started for designers
    • Get started for developers
  • Resources
    • Design resources
  • Integration
    • Using Cloudscape components
    • Global styles
  • Development guides
    • Collection hooks package
    • Content security policy (CSP)
    • Responsive development
    • State management
    • Z-index
  • Testing
    • Introduction to testing
    • Testing frameworks integration
    • Testing core classes
  1. Cloudscape Design System
    • Get started
    • Integration: Using Cloudscape components

    Using Cloudscape components

    To use Cloudscape components, first install a set of packages.

    Note
    Cloudscape only supports React.

      On this page

      • Installing Cloudscape components from npm
      • Available packages
      • Component APIs
      • Bundling assets

      Installing Cloudscape components from npm

      Cloudscape components and related packages are published to npm under the scope @cloudscape-design .

      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.

      Available packages

      @cloudscape-design/components 

      This is the main Cloudscape package. It contains the React components, including the TypeScript definitions.

      @cloudscape-design/board-components 

      This Cloudscape package contains the React components for configurable dashboard pattern, including the TypeScript definitions.

      @cloudscape-design/global-styles 

      The global styles package contains site-level, typography-related styles, including the Open Sans font. To ensure consistent styling, import it once into every Cloudscape application.

      @cloudscape-design/collection-hooks 

      Collection hooks are React hooks that you can use to control the state of the table and cards components, in addition to related components, such as textfilter and pagination.

      @cloudscape-design/design-tokens 

      With this package, you'll get a set of design tokens in a variety of formats. You can use these tokens to build custom components that are visually consistent with Cloudscape.

      @cloudscape-design/test-utils-core 

      This internal package is used to create utilities for writing unit and integration tests. For more information, see introduction to testing.

      Component APIs

      Properties

      You configure components by using the properties documented in the API tab of each component. For example:

      <Icon name="search" variant="subtle" />
      

      Also, all components accept data-* attributes as properties. They attach to the top level component element. id and className are also supported but deprecated, and we recommend avoiding these where possible.

      Slots

      Some properties might accept either plain text or non-text content. Such properties are called slots and they can accept any valid JSX content type .

      For example, you can add a link to an alert header:

      <Alert header={<span>This is the alert header <Link href="https://example.com">with a link</Link></span>} />
      

      Default slots

      Most components have a default slot, which you can use to specify the content as a child  of the component. Default slots are anonymous and can’t be referenced by name. Components can have only one default slot.

      <Alert>
        This is the alert content (default slot)
      </Alert>
      

      Events

      Some components emit custom events, for example when a button is pressed. The API documentation for each component displays the full list of events emitted by a component.

      To register a listener to a custom event, you can add it as a property. The property name is the event name (which is in camel case), prefixed by on.

      <Button onClick={save}>Save</Button>
      

      Functions

      Some components also expose functions that you can call. These functions are available in the reference to the React component. You can retrieve the reference to the component by using the ref property. For example, you can store a reference to an input and use it programmatically to focus on the input field:

      const inputRef = React.useRef();
      return (<>
        <Input ref={inputRef} />
        <Button onClick={() => inputRef.current.focus()}>Focus the input field</Button>
      </>);
      

      Contexts

      Components like applayout or formfield use the React context to implicitly pass down the properties to their children. We expose the formfield context consumer, which can be used to create custom form components. For example:

      import { useFormFieldContext } from '@cloudscape-design/components/contexts/form-field';
      
      function MyFormInput(props) {
        const { controlId, ariaLabelledby, ariaDescribedby, invalid } = useFormFieldContext(props);
        /* ... */
        return <input id={controlId} aria-labelledby={ariaLabelledby} aria-describedby={ariaDescribedby} className={invalid && 'input-invalid'} ... />
      }
      

      Bundling assets

      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

      Using CSS Modules

      If you’re using CSS Modules , we recommend that you exclude Cloudscape styles in your CSS Modules configuration because our components depend on global CSS class names that break during CSS Modules processing. For example, if you’re using css-loader   to load Cloudscape styles, don’t use the modules option . Instead, create separate rules to load styles. The following is one possible solution:

      // Use special configuration for the Cloudscape packages
      {
          test: /\.css$/,
          include: /node_modules\/@cloudscape-design\//,
          use: ['style-loader', 'css-loader']
      }
      
      // Use CSS Modules configuration only for your source code
      {
          test: /\.css$/,
          exclude: /node_modules\/@cloudscape-design\//,
          use: ['style-loader', {
              loader: 'css-loader',
              options: {
                  modules: true
              }
          }]
      }
      

      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']
      };
      
      module.exports = nextConfig;
      

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

      • About
      • Connect
      • Privacy 
      • Site terms 
      • © 2023, Amazon Web Services, Inc. or its affiliates. All rights reserved.
      Made with love atAWS