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