Starbucks React Pattern Library

Overlay

Notes

Creates a fixed position overlay with entrance and exit animation. There are two variants:

Image Overlay: uses a built in image slot, which renders visually like a dialog in desktop viewports. The image layout is handled automatically. This version is triggered by providing an imagePath in the props.

Standard Overlay: When not using the imagePath prop, the overlay simply renders its children. In mobile viewports, the Overlay covers the entire screen. In desktop viewports, there are configuration options for which part of the viewport to cover. Overlay uses the FocusBoomerang utility to manage focus correctly when opened and closed; consumers will need to take care of preventing focus to content covered by the Overlay.

If the consumer can place the Overlay in a spot in the DOM which permits the fixed positioning to work correctly, the Overlay may be used as is. If there are positioning or layering issues due to being nested in a positioned element, the consumer may choose to use the Layer component to facilitate positioning correctly.

To get exit animation, the content/children of Overlay should be removed before the Overlay itself. If the Overlay is able to be mounted at all times, entrance and exit animations will always work.

Props

alignmentoneOf('fullscreen', 'right', 'left', 'rightCrate', 'leftCrate', 'rightThird', 'leftThird')['rightCrate']
Indicates what portion of the UI is covered in desktop viewports. Only applicable when not using the imagePath option. DEPRECATION WARNING: 'left' and 'right' will be removed in an upcoming version. Please use leftCrate or rightCrate if you expect your overlay to cover the left crate or the right crate.
childrenany
Nested component(s) which become the content of the overlay.
childrenContainerClassNamestring
Classname passed to the element that wraps the children
closeCallbackfunc[() => {}]
Function attached to the click event of the included close button.
closePropsobject[{}]
Props passed to the CloseButton component within the Overlay.
containerPropsobject
Additional props to be spread on the container HTMLElement.
focusOnOpenbool[true]
When true, focus will be placed on the container div of the overlay when opened, permitting seamless keyboard traversal. When false, the consumer is expected to manage focus.
imageAltstring[' ']
Prop to allow for giving alternate text to the image
imageContainerPropsobject
Props to pass into the container around the image
imagePathstring
Optional prop to allow for image to be placed on top of the Overlay.
permitImageToShrinkbool
Optional prop to allow for a top-image to be responsive. This is useful when you have tall content and a scalable image. Only applicable if imagePath is passed.
imageObjectFitoneOf('cover', 'contain', 'fill', 'scale-down')['cover']
Optional prop to control the object-fit of the top image. Only applicable if imagePath is passed and permitImageToShrink is true.
renderCloseButtonbool[true]
Whether to use the included default CloseButton component. If false, consumer is expected to provide a custom close button in the children.
showMaskbool[true]
Whether to show a mask when the overlay is opened.
styleobject
Optional style object for custom styling such as z-index; applied to the outermost div.
topShadowbool[false]
A CSS box shadow intended for situations in which another container is visually 'above' the overlay.

Standard Overlay

class OverlayExample extends React.Component {
  constructor(props) {
    super(props);
    this.toggleOpen = this.toggleOpen.bind(this);
    this.state = { isOpen: false };
  }

  toggleOpen() {
    this.setState({ isOpen: !this.state.isOpen });
  }

  renderChildren() {
    return (
      <Overlay
        closeCallback={ this.toggleOpen }
        closeProps={ {
          ariaLabel: 'Since it has no text, please provide a label for the close button'
        } }
        alignment='rightCrate'
      >
        <div className='p3 lg-px7'>
          <div className='mx-auto' style={{ maxWidth: '500px' }}>
            
            <Heading tagName='h1' size='md' className='pb3'>
              Overlay can contain anything
            </Heading>
            <p className="pb5">
              Try changing the alignment prop in the example to see different layouts in desktop-sized viewports.
            </p>
            <p className="pb5">
              You need to provide a handler for clicking the close button.
            </p>
            <div>
              <img src='http://placehold.it/1000x300' alt='' />
            </div>
          </div>
        </div>
      </Overlay>
    );
  }

  render() {
    const { isOpen } = this.state;
    return (
      <div>
        <p className='mb3'>
          Overlay handles layout of a mask and content, but needs to be rendered 
          into a component like Layer that can be fixed position over the whole application
        </p>

        <Button onClick={ this.toggleOpen }>Open Overlay</Button>

        <Layer
          isOpen={isOpen}
        >
          {this.renderChildren()}
        </Layer>
      </div>
    );
  }
}

render(<OverlayExample />);

class OverlayExample extends React.Component {
  constructor(props) {
    super(props);
    this.toggleOpen = this.toggleOpen.bind(this);
    this.state = { isOpen: false };
  }

  toggleOpen() {
    this.setState({ isOpen: !this.state.isOpen });
  }

  renderChildren() {
    return (
      <Overlay
        closeCallback={ this.toggleOpen }
        closeProps={ {
          ariaLabel: 'Since it has no text, please provide a label for the close button'
        } }
        alignment='rightCrate'
      >
        <div className='p3 lg-px7'>
          <div className='mx-auto' style={{ maxWidth: '500px' }}>
            
            <Heading tagName='h1' size='md' className='pb3'>
              Overlay can contain anything
            </Heading>
            <p className="pb5">
              Try changing the alignment prop in the example to see different layouts in desktop-sized viewports.
            </p>
            <p className="pb5">
              You need to provide a handler for clicking the close button.
            </p>
            <div>
              <img src='http://placehold.it/1000x300' alt='' />
            </div>
          </div>
        </div>
      </Overlay>
    );
  }

  render() {
    const { isOpen } = this.state;
    return (
      <div>
        <p className='mb3'>
          Overlay handles layout of a mask and content, but needs to be rendered 
          into a component like Layer that can be fixed position over the whole application
        </p>

        <Button onClick={ this.toggleOpen }>Open Overlay</Button>

        <Layer
          isOpen={isOpen}
        >
          {this.renderChildren()}
        </Layer>
      </div>
    );
  }
}

render(<OverlayExample />);

Overlay with optional image included

class OverlayExample extends React.Component {
  constructor(props) {
    super(props);
    this.toggleOpen = this.toggleOpen.bind(this);
    this.toggleShrinkable = this.toggleShrinkable.bind(this);
    this.state = { isOpen: false, isShrinkable: false };
  }

  toggleOpen() {
    this.setState({ isOpen: !this.state.isOpen });
  }

  toggleShrinkable() {
    this.setState({ isShrinkable: !this.state.isShrinkable });
  }

  renderChildren() {
    return (
      <Overlay
        closeCallback={ this.toggleOpen }
        closeProps={ {
          ariaLabel: 'Since it has no text, please provide a label for the close button'
        } }
        imagePath="https://globalassets.starbucks.com/assets/bdea26b70ac94a02a97d2a24e3158ea5.jpg"
        permitImageToShrink={this.state.isShrinkable}
      >
        <div className='p3 lg-px7 mx-auto flex flex-column height-100' style={{ maxWidth: '500px' }}>
            <Heading tagName='h1' size='md' className='pb3'>
              Overlay can contain anything
            </Heading>
            <p className="pb5 flex-grow">
              It really can.
            </p>
            {this.state.isShrinkable && <p>
              This image is now shrinkable! Try making the window really short.
            </p>}
            <ButtonKit cancelText="Foo" confirmText="Toggle Shrinkable Image" onConfirm={this.toggleShrinkable} />
        </div>
      </Overlay>
    );
  }

  render() {
    const { isOpen } = this.state;
    return (
      <div>
        <p className='mb3'>
          You can pass a path to an image to the `imagePath` prop to get a different layout of the Overlay
          where the image from the path will be placed on top of the content and be rendered like a dialog at
          desktop layouts. As a dialog, the image will be responsive for both height and width changes (try shrinking the window to be very short).
        </p>

        <Button onClick={ this.toggleOpen }>Open Overlay</Button>

        <Layer
          isOpen={isOpen}
        >
          {this.renderChildren()}
        </Layer>
      </div>
    );
  }
}

render(<OverlayExample />);

class OverlayExample extends React.Component {
  constructor(props) {
    super(props);
    this.toggleOpen = this.toggleOpen.bind(this);
    this.toggleShrinkable = this.toggleShrinkable.bind(this);
    this.state = { isOpen: false, isShrinkable: false };
  }

  toggleOpen() {
    this.setState({ isOpen: !this.state.isOpen });
  }

  toggleShrinkable() {
    this.setState({ isShrinkable: !this.state.isShrinkable });
  }

  renderChildren() {
    return (
      <Overlay
        closeCallback={ this.toggleOpen }
        closeProps={ {
          ariaLabel: 'Since it has no text, please provide a label for the close button'
        } }
        imagePath="https://globalassets.starbucks.com/assets/bdea26b70ac94a02a97d2a24e3158ea5.jpg"
        permitImageToShrink={this.state.isShrinkable}
      >
        <div className='p3 lg-px7 mx-auto flex flex-column height-100' style={{ maxWidth: '500px' }}>
            <Heading tagName='h1' size='md' className='pb3'>
              Overlay can contain anything
            </Heading>
            <p className="pb5 flex-grow">
              It really can.
            </p>
            {this.state.isShrinkable && <p>
              This image is now shrinkable! Try making the window really short.
            </p>}
            <ButtonKit cancelText="Foo" confirmText="Toggle Shrinkable Image" onConfirm={this.toggleShrinkable} />
        </div>
      </Overlay>
    );
  }

  render() {
    const { isOpen } = this.state;
    return (
      <div>
        <p className='mb3'>
          You can pass a path to an image to the `imagePath` prop to get a different layout of the Overlay
          where the image from the path will be placed on top of the content and be rendered like a dialog at
          desktop layouts. As a dialog, the image will be responsive for both height and width changes (try shrinking the window to be very short).
        </p>

        <Button onClick={ this.toggleOpen }>Open Overlay</Button>

        <Layer
          isOpen={isOpen}
        >
          {this.renderChildren()}
        </Layer>
      </div>
    );
  }
}

render(<OverlayExample />);