@lightspeed/cirrus-sidebar

Sidebar

The composable and reusable <Sidebar> component. Since these components are very flexible, it's recommended to build your own abstraction specific to your product on top of this.

ℹ️ Note: The implementation of the breakpoints (when to hide) and animation is up to the consumer of this package as of now.

Installation

First, make sure you have been through the install steps steps required to add Flame in your application. Although it's not required to have Flame installed to use Logo, you will need to install its peer dependencies.

If using Yarn:

yarn add @lightspeed/cirrus-sidebar

Or using npm:

npm i -S @lightspeed/cirrus-sidebar

Styles

Because the <Sidebar> is completely unknown in what environment it's being rendered and at what breakpoints the sidebar should hide, we open up a couple of animation styles for you to use.

These styles are exposed at @lightspeed/cirrus-sidebar/styles. These constants are exposed at @lightspeed/cirrus-sidebar/styles/constants.

Example

import styled from '@emotion/styled';
import { slideInDurationMs, slideInBezier } from '@lightspeed/cirrus-sidebar/styles';
import { PAGE_HEADER_HEIGHT, SIDEBAR_WIDTH } from '@lightspeed/cirrus-sidebar/styles/constants';
import { Sidebar } from '@lightspeed/cirrus-sidebar';

const SidebarWrapper = styled.div`
  position: absolute;
  left: -${SIDEBAR_WIDTH}px;
  top: 0;
  bottom: 0;
  transition: left ${slideInDurationMs} ${slideInBezier};

  ${props => props.active && 'left: 0;'}
  @media (min-device-width: 480px) {
    left: 0;
  }
`;

const App = () => (
  <SidebarWrapper>
    <Sidebar>Sidebar content here</Sidebar>
  </SidebarWrapper>
);

export default App;

Full featured Sidebar

Example

import React from 'react';
import { Text } from '@lightspeed/cirrus-text';
import Icon from '@lightspeed/cirrus-icon';
import {
  Sidebar,
  SidebarHeader,
  SidebarAppSwitcher,
  SidebarShopButton,
  SidebarDropdownButton,
  SidebarAccountDropdown,
  SidebarMenu,
  SidebarMenuItem,
  SidebarItem,
  SidebarNotificationBadge,
  SidebarNav,
  SidebarFooter,
  SidebarFooterItem,
} from '@lightspeed/cirrus-sidebar';

const items = [
  { icon: <Icon name="home" />, children: 'Home', href: '/', active: true },
  { icon: <Icon name="statistics" />, children: 'Statistics', href: 'statistics' },
  {
    icon: <Icon name="orders" />,
    children: 'Orders',
    href: 'orders',
    hasSublevel: true,
    notifications: <SidebarNotificationBadge>2</SidebarNotificationBadge>,
  },
  { icon: <Icon name="products" />, children: 'Products', href: 'products', hasSublevel: true },
  { icon: <Icon name="customers" />, children: 'Customers', href: 'customers', hasSublevel: true },
  { icon: <Icon name="design" />, children: 'Design', href: 'themes', hasSublevel: true },
  { icon: <Icon name="content" />, children: 'Content', href: 'pages', hasSublevel: true },
  {
    icon: <Icon name="discount-rules" />,
    children: 'Marketing',
    href: 'discount_codes',
    hasSublevel: true,
  },
  {
    icon: <Icon name="blogs" />,
    children: 'Blogs',
    href: 'blogs',
    onClick: e => {
      e.preventDefault();
      console.log('You can also just hook into the item through onClick!');
    },
    hasSublevel: true,
  },
  {
    icon: <Icon name="apps" />,
    children: 'Apps',
    href: 'store/apps/dashboard',
    disabled: true,
    hasSublevel: true,
  },
  { icon: <Icon name="tools" />, children: 'Tools', href: 'imports', hasSublevel: true },
  { icon: <Icon name="settings" />, children: 'Settings', href: 'settings', disabled: true },
];

class MyComponent extends React.Component {
  constructor(props) {
    super(props);

    this.state = {
      isUserMenuOpen: false,
    };

    this.openUserMenu = this.openUserMenu.bind(this);
    this.closeUserMenu = this.closeUserMenu.bind(this);
  }

  openUserMenu() {
    this.setState(() => ({
      isUserMenuOpen: true,
    }));
  }

  closeUserMenu() {
    this.setState(() => ({
      isUserMenuOpen: true,
    }));
  }

  render() {
    const { isUserMenuOpen } = this.state;

    return (
      <div>
        <Sidebar>
          <SidebarHeader>
            <SidebarAppSwitcher
              currentProduct="ecom"
              canSwitchTo={[{ name: 'retail', href: '/retail' }]}
            />

            <SidebarShopButton>
              <Text color="snow">SEOshop</Text>
              <Text color="snow">http://shop1.webshopapp.dev/</Text>
            </SidebarShopButton>

            <SidebarAccountDropdown
              isOpen={isUserMenuOpen}
              onOpen={this.openUserMenu}
              onClose={this.closeUserMenu}
              target={({ targetProps, targetEvents }) => (
                <SidebarDropdownButton {...targetProps} {...targetEvents} active={isUserMenuOpen}>
                  Awesome Merchant
                </SidebarDropdownButton>
              )}
            >
              <SidebarMenu>
                <SidebarMenuItem href="#">Tasks</SidebarMenuItem>
                <SidebarMenuItem href="#">My Account</SidebarMenuItem>
                <SidebarMenuItem href="#" danger>
                  Logout
                </SidebarMenuItem>
              </SidebarMenu>
            </SidebarAccountDropdown>
          </SidebarHeader>

          <SidebarNav>
            <ul>
              {items.map(item => (
                <SidebarItem key={item.title} {...item} />
              ))}
            </ul>
          </SidebarNav>

          <SidebarFooter>
            <SidebarFooterItem
              icon={<Icon name="help" />}
              href="#"
              target="_blank"
              rel="noopener noreferrer"
            >
              Help
            </SidebarFooterItem>

            <SidebarFooterItem icon={<Icon name="search" />} href="#">
              Search
            </SidebarFooterItem>
          </SidebarFooter>
        </Sidebar>
      </div>
    );
  }
}

export default MyComponent;

Sidebar

The wrapper of the sidebar (controls the width and color).

Props

Prop	Type	Description
children	React.ReactNode	The content to display inside the button
...rest	Any	Any prop you want to add to this element

Example

import React from 'react';
import { Sidebar } from '@lightspeed/cirrus-sidebar';

const App = () => <Sidebar>My content here</Sidebar>;

export default App;

SidebarHeader

The top part of the sidebar (contains the appswitcher, shopbutton and account menu). This element divides the top part of the sidebar from the main navigation and the footer.

Props

Prop	Type	Description
children	React.ReactNode	The content to display inside the sidebar
...rest	Any	Any prop you want to add to this element

Example

import React from 'react';
import { Sidebar, SidebarHeader } from '@lightspeed/cirrus-sidebar';

const App = () => (
  <Sidebar>
    <SidebarHeader>Your header stuff here</SidebarHeader>

    <nav>Other stuff here</nav>
  </Sidebar>
);

export default App;

SidebarAppSwitcher

This component is responsible for showing the correct current app and what apps the user can switch to.

Props

Prop	Type	Required?	Description
currentProduct	`ecom	retail`	Yes
canSwitchTo	Array<ProductT>	No	The list of products that the user can switch to
logoProps	Object	No	The props you want to pass to the logo (such as href, onClick, etc.)
triggerProps	Object	No	The props you want to pass to the "switch products" button
appsConfig	AppsConfig	No	An object that allows you to add new apps to switch to (see info down below)

AppsConfig

The apps config is an object with the key being the app identifier and the value being the app logo. This allows you to then use these as the currentProduct and within the switchable apps array.

Note: This does not override existing apps (e.g. retail and ecom will still remain available)

Example

const appsConfig = {
  customApp: <svg />,
  anotherApp: <svg />,
};

<SidebarAppSwitcher
  appsConfig={appsConfig}
  currentProduct="customApp"
  canSwitchTo={[{ name: 'retail', href: '/retail' }, { name: 'anotherApp', href: '/another-app' }]}
/>;

Example

User is not able to switch between products

import React from 'react';
import { Sidebar, SidebarHeader, SidebarAppSwitcher } from '@lightspeed/cirrus-sidebar';

const App = () => (
  <Sidebar>
    <SidebarHeader>
      <SidebarAppSwitcher currentProduct="ecom" />
    </SidebarHeader>
  </Sidebar>
);

export default App;

User can switch to retail

import React from 'react';
import { Sidebar, SidebarHeader, SidebarAppSwitcher } from '@lightspeed/cirrus-sidebar';

const App = () => (
  <Sidebar>
    <SidebarHeader>
      <SidebarAppSwitcher
        currentProduct="ecom"
        canSwitchTo={[{ name: 'retail', href: '/retail' }]}
      />
    </SidebarHeader>
  </Sidebar>
);

export default App;

User can switch to retail through onClick

import React from 'react';
import { Sidebar, SidebarHeader, SidebarAppSwitcher } from '@lightspeed/cirrus-sidebar';

const App = () => (
  <Sidebar>
    <SidebarHeader>
      <SidebarAppSwitcher
        currentProduct="ecom"
        canSwitchTo={[
          {
            name: 'retail',
            onClick: e => {
              e.preventDefault();
              router.goTo('/retail');
            },
          },
        ]}
      />
    </SidebarHeader>
  </Sidebar>
);

export default App;

With custom config

import React from 'react';
import { Sidebar, SidebarHeader, SidebarAppSwitcher } from '@lightspeed/cirrus-sidebar';

const App = () => (
  <Sidebar>
    <SidebarHeader>
      <SidebarAppSwitcher
        appsConfig={{ customProduct: '🔥' }}
        currentProduct="ecom"
        canSwitchTo={[
          { name: 'retail', href: '/retail' },
          { name: 'customProduct', href: '/custom-product' },
        ]}
      />
    </SidebarHeader>
  </Sidebar>
);

export default App;

Add link to logo

import React from 'react';
import { Sidebar, SidebarHeader, SidebarAppSwitcher } from '@lightspeed/cirrus-sidebar';

const App = () => (
  <Sidebar>
    <SidebarHeader>
      <SidebarAppSwitcher logoProps={{ href: '/' }} currentProduct="ecom" />
    </SidebarHeader>
  </Sidebar>
);

export default App;

Add data attribute to trigger button

import React from 'react';
import { Sidebar, SidebarHeader, SidebarAppSwitcher } from '@lightspeed/cirrus-sidebar';

const App = () => (
  <Sidebar>
    <SidebarHeader>
      <SidebarAppSwitcher
        triggerProps={{ 'data-test': 'sidebar-product-trigger' }}
        currentProduct="ecom"
      />
    </SidebarHeader>
  </Sidebar>
);

export default App;

SidebarShopButton

The button that is all around the current shop and register.

Props

Prop	Type	Description
children	React.ReactNode	The content to display inside the button
active	boolean	Whether the shop button is currently active
...rest	Any	Any prop you want to add to this element

Example

import React from 'react';
import { Text } from '@lightspeed/cirrus-text';
import { SidebarShopButton } from '@lightspeed/cirrus-sidebar';

const App = () => (
  <Sidebar>
    <SidebarHeader>
      <SidebarShopButton onClick={() => router.goTo('/switch')}>
        <Text color="snow">SEOshop</Text>
        <Text color="snow">http://shop1.webshopapp.dev/</Text>
      </SidebarShopButton>
    </SidebarHeader>
  </Sidebar>
);

export default App;

SidebarDropdownButton

The dropdown button that is used for opening menus (contains an icon that indicates that a menu will open). See <SidebarAccountDropdown> for an example.

Props

Prop	Type	Description
children	React.ReactNode	The content to display inside the button
...rest	Any	Any prop you want to add to this element

SidebarMenu

See <SidebarAccountDropdown> for an example.

Props

Prop	Type	Description
children	React.ReactNode	The content to display inside the button
...rest	Any	Any prop you want to add to this element

SidebarMenuItem

The menu item for the <SidebarMenu>. See <SidebarAccountDropdown> for an example.

Props

Prop	Type	Description
children	React.ReactNode	The content to display inside the button
danger	boolean	Whether the item is danger styled
...rest	Any	Any prop you want to add to this element

Example

SidebarAccountDropdown

The Sidebar popover menu. Renders a cirrus-popover with some customized positional styles.

Props

Prop	Type	Description
children	React.ReactNode	The content to display inside the button
...cirrusPopoverProps	Object	Any props defined within the cirrus-popover

Example

import React from 'react';
import { Text } from '@lightspeed/cirrus-text';
import {
  Sidebar,
  SidebarHeader,
  SidebarAccountDropdown,
  SidebarDropdownButton,
  SidebarMenu,
  SidebarMenuItem,
} from '@lightspeed/cirrus-sidebar';

class MyComponent extends React.Component {
  constructor(props) {
    super(props);

    this.state = {
      isUserMenuOpen: false,
    };

    this.openUserMenu = this.openUserMenu.bind(this);
    this.closeUserMenu = this.closeUserMenu.bind(this);
  }

  openUserMenu() {
    this.setState(() => ({
      isUserMenuOpen: true,
    }));
  }

  closeUserMenu() {
    this.setState(() => ({
      isUserMenuOpen: true,
    }));
  }

  render() {
    const { isUserMenuOpen } = this.state;

    return (
      <Sidebar>
        <SidebarHeader>
          <SidebarAccountDropdown
            isOpen={isUserMenuOpen}
            onOpen={this.openUserMenu}
            onClose={this.closeUserMenu}
            target={({ targetProps, targetEvents }) => (
              <SidebarDropdownButton {...targetProps} {...targetEvents} active={isUserMenuOpen}>
                Awesome Merchant
              </SidebarDropdownButton>
            )}
          >
            <SidebarMenu>
              <SidebarMenuItem href="#">Tasks</SidebarMenuItem>
              <SidebarMenuItem href="#">My Account</SidebarMenuItem>
              <SidebarMenuItem href="#" danger>
                Logout
              </SidebarMenuItem>
            </SidebarMenu>
          </SidebarAccountDropdown>
        </SidebarHeader>
      </Sidebar>
    );
  }
}

export default MyComponent;

SidebarNav

The <nav> element styled for the Sidebar.

Note: Automatically removes the list-style from a direct child <ul> tag.

Props

Prop	Type	Description
children	React.ReactNode	The content to display inside the button
...rest	Any	Any prop you want to add to this element

Example

import React from 'react';
import { Text } from '@lightspeed/cirrus-text';
import { Sidebar, SidebarHeader, SidebarNav } from '@lightspeed/cirrus-sidebar';

const App = () => (
  <Sidebar>
    <SidebarHeader>The header here</SidebarHeader>

    <SidebarNav>
      <ul>
        <li>Your nav items here</li>
      </ul>
    </SidebarNav>
  </Sidebar>
);

export default App;

SidebarItem

The sidebar navigation link (<a>).

Props

Prop	Type	Description
icon	React.Node	Can render any icon (preferably the a cirrus-icon)
children	React.Node	The navigation item's title
href	string	The url of the navigation item (should be present)
active	boolean	Whether the navigation link is currently active
disabled	boolean	Whether the navigation link is disabled (only appears disabled)
notifications	React.Node	Allows for showing notifications for this navigation link
hasSublevel	boolean	Whether this navigation link has a sub level navigation
...rest	Any	Any prop you want to add to this element

Example

Using href

import React from 'react';
import Icon from '@lightspeed/cirrus-icon';
import { Text } from '@lightspeed/cirrus-text';
import { Sidebar, SidebarHeader, SidebarNav, SidebarItem } from '@lightspeed/cirrus-sidebar';

const App = () => (
  <Sidebar>
    <SidebarHeader>The header here</SidebarHeader>

    <SidebarNav>
      <ul>
        <li>
          <SidebarItem icon={<Icon name="home" />} href="/">
            Home
          </SidebarItem>
        </li>
      </ul>
    </SidebarNav>
  </Sidebar>
);

export default App;

Using onClick

When passing onClick, you should still pass a href as well, to indicate that the element is interactable.

import React from 'react';
import Icon from '@lightspeed/cirrus-icon';
import { Text } from '@lightspeed/cirrus-text';
import { Sidebar, SidebarHeader, SidebarNav, SidebarItem } from '@lightspeed/cirrus-sidebar';

const App = () => (
  <Sidebar>
    <SidebarHeader>The header here</SidebarHeader>

    <SidebarNav>
      <ul>
        <li>
          <SidebarItem
            icon={<Icon name="home" />}
            href="/"
            onClick={e => {
              e.preventDefault();
              router.goTo('/');
            }}
          >
            Home
          </SidebarItem>
        </li>
      </ul>
    </SidebarNav>
  </Sidebar>
);

export default App;

SidebarNotificationBadge

The notification badge that can be used within the <SidebarItem />'s notifications prop.

Props

Prop	Type	Description
children	React.ReactNode	The content to display inside the button
...rest	Any	Any prop you want to add to this element

Example

import React from 'react';
import Icon from '@lightspeed/cirrus-icon';
import { Text } from '@lightspeed/cirrus-text';
import {
  Sidebar,
  SidebarHeader,
  SidebarNav,
  SidebarItem,
  SidebarNotificationBadge,
} from '@lightspeed/cirrus-sidebar';

const App = () => (
  <Sidebar>
    <SidebarHeader>The header here</SidebarHeader>

    <SidebarNav>
      <ul>
        <li>
          <SidebarItem
            icon={<Icon name="home" />}
            href="/"
            notifications={<SidebarNotificationBadge>2</SidebarNotificationBadge>}
          >
            Home
          </SidebarItem>
        </li>
      </ul>
    </SidebarNav>
  </Sidebar>
);

export default App;

SidebarFooter

The <footer> styled for the Sidebar

Props

Prop	Type	Description
children	React.ReactNode	The content to display inside the button
...rest	Any	Any prop you want to add to this element

Example

import React from 'react';
import Icon from '@lightspeed/cirrus-icon';
import { Text } from '@lightspeed/cirrus-text';
import { Sidebar, SidebarHeader, SidebarNav, SidebarFooter } from '@lightspeed/cirrus-sidebar';

const App = () => (
  <Sidebar>
    <SidebarHeader>The header here</SidebarHeader>
    <SidebarNav>Nav here</SidebarNav>
    <SidebarFooter>The Footer goes here</SidebarFooter>
  </Sidebar>
);

export default App;

SidebarFooterItem

The items that go inside the footer (renders a <a>).

Props

Prop	Type	Description
children	React.ReactNode	The content to display inside the footer item
icon	React.ReactNode	The icon to render inside the footer item
...rest	Any	Any prop you want to add to this element

Example

import React from 'react';
import Icon from '@lightspeed/cirrus-icon';
import { Text } from '@lightspeed/cirrus-text';
import {
  Sidebar,
  SidebarHeader,
  SidebarNav,
  SidebarFooter,
  SidebarFooterItem,
} from '@lightspeed/cirrus-sidebar';

const App = () => (
  <Sidebar>
    <SidebarHeader>The header here</SidebarHeader>
    <SidebarNav>Nav here</SidebarNav>
    <SidebarFooter>
      <SidebarFooterItem icon={<Icon name="help" />} href="/help">
        Help
      </SidebarFooterItem>
    </SidebarFooter>
  </Sidebar>
);

export default App;