How to Use GDS Lists

List Item

See it in Storybook

Component API

TIP: You can change the different values of the component props under the controls tab.

Install it

npm i @nielsen-media/gds-list-item

NOTE: Because the support for Web Components in React isn’t great we have to do some extra work to get the to work properly. We are going to use a package from lit-labs/react this will help us set up our web-components a bit better.

Install it

npm i lit-labs/react

Below is a recipe to get the GDS Component working in React and hooking up an event handler to it. This approach only uses lit-labs/react package. This package wraps our web component and allows us to use it in a React application.

You can read here and here about some of the hardship of Web Components + React. Also check out the documentation for lit-labs/react to use Web Components in React.

List Callout Item is a component that needs to be constructed by passing in other components as children. It acts as a sort of wrapper. The approach is used to simplify component creation.

Use it

The ListCalloutItem component can be built in two ways. The first way is to create a React component that uses props.children to construct List Callout.

// List Item - Basic Example
// ListItem.js

import React from "react";
import { createComponent } from "@lit-labs/react";
import ListItem from "@nielsen-media/gds-list-item/lib/src";

export const ListItemComponent = createComponent(
  React,
  "gds-list-item",
  ListItem
);

export function GDSListItem(props) {
  console.log(props);
  return (
    <ListItemComponent
      size={props.size}
      mode={props.mode}
      divider={props.divider}
      direction={props.direction}
      color={props.color}
      weight={props.weight}
    >
      {props.children}
    </ListItemComponent>
  );
}

Above we create the wrapper component in react and below we pass in the needed props and children that List Callout Item needs.

// List Item - Basic Example
// App.js

import { ListItemComponent } from "./ListItem";
import "./App.scss";

// Helper to get icon size
const getListItemIconSize = (size, direction) => {
  if (direction === "horizontal" || direction === "horizontal-fixed") {
    switch (size) {
      case "regular":
        return "20";
      case "compact":
        return "16";
      case "tiny":
        return "16";
      default:
        return "24";
    }
  } else {
    switch (size) {
      case "regular":
        return "40";
      case "compact":
        return "32";
      case "tiny":
        return "24";
      default:
        return "48";
    }
  }
};

function App() {
  return (
    <div className="App">
      <div className="container-fluid">
        <ListItemComponent>
          <h3 slot="heading">List Heading</h3>
          <p slot="body">List Body</p>
        </ListItemComponent>
      </div>
    </div>
  );
}

export default App;
// List Item - Text Only Example
// App.js

import { ListItemComponent } from "./ListItem";
import "./App.scss";

const getListItemIconSize = (size, direction) => {
  if (direction === "horizontal" || direction === "horizontal-fixed") {
    switch (size) {
      case "regular":
        return "20";
      case "compact":
        return "16";
      case "tiny":
        return "16";
      default:
        return "24";
    }
  } else {
    switch (size) {
      case "regular":
        return "40";
      case "compact":
        return "32";
      case "tiny":
        return "24";
      default:
        return "48";
    }
  }
};

function App() {
  return (
    <div className="App">
      <div className="container-fluid">
        <ListItemComponent
          direction="vertical"
          mode="light"
          size="jumbo"
          color="blurple"
          weight="regular"
          divider="true"
        >
          <h3 slot="heading">List Heading</h3>
          <p slot="body">List Body</p>
        </ListItemComponent>
      </div>
    </div>
  );
}

export default App;
// List Item - Text with Icon Example
// App.js

import { ListItemComponent } from "./ListItem";
import "./App.scss";

const getListItemIconSize = (size, direction) => {
  if (direction === "horizontal" || direction === "horizontal-fixed") {
    switch (size) {
      case "regular":
        return "20";
      case "compact":
        return "16";
      case "tiny":
        return "16";
      default:
        return "24";
    }
  } else {
    switch (size) {
      case "regular":
        return "40";
      case "compact":
        return "32";
      case "tiny":
        return "24";
      default:
        return "48";
    }
  }
};

function App() {
  return (
    <div className="App">
      <div className="container-fluid">
        <ListItemComponent
          direction="vertical"
          mode="light"
          size="jumbo"
          color="blurple"
          weight="regular"
          divider="true"
        >
          <IconComponent
            mode="light"
            slot="icon"
            icon="hiking"
            foreground-level={mode === "light" ? "900" : "100"}
            size={getListItemIconSize("giant")}
          />
          <h3 slot="heading">List Heading</h3>
          <p slot="body">List Body</p>
        </ListItemComponent>
      </div>
    </div>
  );
}

export default App;

List Callout Item

See it in Storybook

Component API

Install it

npm i @nielsen-media/gds-list-callout-item

How to use GDS Web Components + React

List Callout Item is a component that needs to be constructed by passing in other components as children. It acts as a sort of wrapper. The approach is used to simplify component creation.

Use it

The ListCalloutItem component can be built in two ways. The first way is to create a React component that uses props.children to construct List Callout.

// List Callout Item - Basic Example
// ListCallout.js

import React from "react";
import { createComponent } from "@lit-labs/react";
import GDSListCalloutItem from "@nielsen-media/gds-list-callout-item/lib/src";
import "@nielsen-media/gds-trend/lib/src";

export const GDSListCalloutItemComponent = createComponent(
  React,
  "gds-list-callout-item",
  GDSListCalloutItem,
  {
    onClick: "click",
  }
);

export function CustomCalloutItem(props) {
  return (
    <GDSListCalloutItemComponent
      size={props.size}
      mode={props.mode}
      alignment={props.alignment}
      color={props.color}
      color-level={props["color-level"]}
      weight={props.weight}
    >
      {props.children}
    </GDSListCalloutItemComponent>
  );
}

Above we create the wrapper component in react and below we pass in the needed props and children that List Callout Item needs.

// List Callout Item - Text Only Example
import "./App.scss";
import { CustomCalloutItem } from "./ListCallout";
import { useState } from "react";

function App() {
  return (
    <div className="App">
      <div class="container-fluid">
        <h2>List Callout Item</h2>
        <CustomCalloutItem size="jumbo" weight="semibold">
          <h3 slot="label">Label</h3>
          <p slot="value">Value</p>
        </CustomCalloutItem>
      </div>
    </div>
  );
}

export default App;
// List Callout Item - with Icon Example
import "./App.scss";
import { CustomCalloutItem } from "./ListCallout";
import { TrendComponent } from "./Trend";
import { useState } from "react";

const getCalloutIconSize = (size) => {
  switch (size) {
    case "regular":
      return "40";
    case "compact":
      return "32";
    default:
      return "48";
  }
};

function App() {
  return (
    <div className="App">
      <div class="container-fluid">
        <h2>List Callout Item</h2>
        <CustomCalloutItem
          size="jumbo"
          weight="semibold"
          icon="dashboard"
          mode="light"
        >
          <IconComponent
            slot="icon"
            icon="dashboard"
            foreground="aqua"
            foreground-level={mode === "light" ? "600" : "400"}
            // Helper to get correct Icon size for callout
            size={getCalloutIconSize("giant")}
            background="aqua"
            background-level={mode === "light" ? "100" : "900"}
          />
          <h3 slot="label">Label</h3>
          <p slot="value">Value</p>
        </CustomCalloutItem>
      </div>
    </div>
  );
}

export default App;
// List Callout Item - with Icon and Trend Example
import "./App.scss";
import { CustomCalloutItem } from "./ListCallout";
import { TrendComponent } from "./Trend";
import { useState } from "react";

const getCalloutIconSize = (size) => {
  switch (size) {
    case "regular":
      return "40";
    case "compact":
      return "32";
    default:
      return "48";
  }
};

function App() {
  return (
    <div className="App">
      <div class="container-fluid">
        <h2>List Callout Item</h2>
        <CustomCalloutItem weight="semibold" size="giant">
          <h3 slot="label">Label</h3>
          <p slot="value">Value</p>
          <IconComponent
            slot="icon"
            icon="dashboard"
            foreground="aqua"
            foreground-level={mode === "light" ? "600" : "400"}
            size={getCalloutIconSize("giant")}
            background="aqua"
            background-level={mode === "light" ? "100" : "900"}
          />
          <TrendComponent
            slot="trend"
            size="giant"
            mode="light"
            trend="up"
            background={true}
          >
            5.2%
          </TrendComponent>
        </CustomCalloutItem>
      </div>
    </div>
  );
}

export default App;