App Design and CSS Styling

with the

ArcGIS API for JavaScript v4

Allan Laframboise

App Design Patterns

  • Layouts
  • Frameworks
  • View
  • UI

Do more with less CSS!

  • Widgets
  • Popups
  • Panels


Full Page

Partial Page (Flex, Grid)


Bootstrap 4



<!-- 1. Main map container -->
<div id="viewDiv" class="esri-view esri-view-height-large esri-view-width-large esri-view-orientation-landscape...">
  <div class="esri-view-root" style="width: 1186px; height: 1124px;">
    <!-- 2. Drawing surface -->
    <div class="esri-view-surface" style="user-select: none; width: 1186px; height: 1124px; touch-action: none; display: block; opacity: 1;" tabindex="0">
      <canvas class="esri-display-object" width="1186" height="1124" style="width: 1186px; height: 1124px; display: block; opacity: 1;"></canvas>
    <!-- 3. UI Elements -->
    <div class="esri-ui" style="top: 0px; left: 0px; right: 0px; bottom: 0px;">
      <!-- 3a. Manual UI -->  
      <div class="esri-ui-inner-container esri-ui-manual-container">
        <div class="esri-component esri-attribution esri-widget">
      <!-- 3b. Default UI -->  
      <div class="esri-ui-inner-container esri-ui-corner-container" style="top: 15px; left: 15px; right: 15px; bottom: 30px;">
        <div class="esri-ui-top-left esri-ui-corner"><div class="esri-component esri-zoom esri-widget">

View Padding

  • Adds space to map and UI containers
  • Offset - title, panel, popup docking, widgets
  • Map center is honored

Size and Resize

  • Use to change application state (UI)
  • view.size property - width and height
  • view.resizing - throttled handler


  • Listen for width and height breaks (@media)
  • String sizes available immediately
  • Enhance performance

  // Default view.breakpoints sizes

  xsmall: 0-544 (esri-view-width-xsmall)
  small: 545-768 (esri-view-width-small)
  medium: 769-992 (esri-view-width-medium)
  large: 993-1200 (esri-view-width-large)
  xlarge: 1201+ (esri-view-width-xlarge)


Default UI

  • Corner containers for all UI elements
  • Widgets, custom <div> elements
  • Easy positioning and repositioning
  • 15px offset
  • Respects view padding

Manual UI

  • Open container for UI elements
  • Widgets, custom <div> elements
  • Easy positioning or repositioning
  • Respects view padding

Custom UI

  • Your own container for UI elements
  • Widgets, custom <div> elements
  • NOT affected by view or ui padding


Custom Button

  • Create a raw DIV, model after existing
  • Fast and easy
  • Add key .esri-CSS classes
  • Works with manual and default UI

Custom Control

  • Create a raw DIV and style
  • Fast and easy
  • Add key .esri-CSS classes
  • Works with manual and default UI



  • Auto - top-right (desktop) & bottom (mobile)
  • Manual - control with break points
  • Control with a function
  • Disable


  • Auto - best alignment
  • Manual - "top-left, top-center..."


  • Recenter when popup shows
  • Good for mobile apps
  • Listen for feature selections


  • Sizing changes for every breakpoint
  • Override CSS for break points
  • Handle docking and floating states


Button + Panel

  • Create a raw DIV and style
  • Dynamically set view padding to offset map
  • Listen to click events

Responsive Expand

  • Expandable panel for ui on mobile screens
  • Build more responsive apps
  • Override widget css for mobile

Popup Panel

  • Reuse popup as a panel
  • Insert widgets or custom elements
  • Override top buttons


  • Fonts
  • Icons
  • View
  • UI
  • Widgets
  • Popup

Default Themes

  • Precompiled xxx.css
  • Light and dark Theme (defaults)
  • Light and dark blue, green, red, purple
  • See documentation

CSS Theme

  • Override key CSS classes
  • background, foreground, :hover, :focus
  • Use caution with .esri-widget
  • Note: brittle and not a scalable solution
  1. Clone jsapi-styles
  2. npm install
  3. Add overrides
    • background
    • foreground (text)
    • hover/focus
    • button size
    • colors
  4. Host compiled theme

Final Notes

  • New CSS and UI design patterns for 4.x
  • Easier to build responsive apps
  • Try these patterns today!

Session Feedback

Download the Esri Events App

Copy of App Design and CSS Styling with ArcGIS API for JavaScript v4

By Jim Barry

Copy of App Design and CSS Styling with ArcGIS API for JavaScript v4

  • 1,417