Mapping application layouts

To build a web mapping application, ArcGIS Maps SDK for JavaScript components provide map rendering and GIS functionality. As applications expand with additional tools, panels, and workflows, layout decisions increasingly affect usability, clarity, and maintainability. Building a complete application requires more than placing components around a map. Calcite Design System provides these capabilities and is the recommended layout foundation for applications built with JavaScript Maps SDK. This separation ensures predictable layout behavior and cleaner application architecture.

This guide provides guidance on how to structure web applications with Calcite components using common layout patterns, clarifying component responsibilities, and applying consistent styling.

Organizing the application

A web mapping application should separate structure, functionality, and layout responsibilities. Keeping these concerns independent prevents layout decisions from becoming tightly coupled with GIS logic.

Layout

The application container defines structural regions, such as main content areas, sidebars and navigation. The layout section is implemented using Calcite’s layout components such as <calcite-shell>, <calcite-shell-panel>, <calcite-panel>, <calcite-block> and <calcite-action-bar>.

The layout of an application refers to the composition and placement of user interface elements. It does not provide GIS functionality. The finder style layout sample demonstrates a shell-based layout offering a shell panel for data controls and a content region for the map, which showcase how Calcite components structure the application.

Mapping and analysis

The interactive GIS section includes <arcgis-map> or a <arcgis-scene> and related components such as legends, layer lists, and popups. These components should be placed inside the layout regions defined by the application layout. This layer provides functionality, not structure.

The interactive-filter layout sample provides UI controls in a sidebar enabling interaction with a 3D SceneView in real time.

Theming and responsiveness

Another aspect controls how layout regions adapt and display across devices. This includes both structural sizing and visual styling, including:

• CSS to control layout sizing, spacing, and responsiveness. Flexbox or Grid manages content distribution, while explicit height and width ensure maps and panels scale correctly. Media queries handle device breakpoints.
• Calcite CSS variables for visual styling, including colors, spacing and surfaces. Avoid overriding internal calcite styles and reserve CSS for structure and calcite variables for appearance.
• Calcite’s light and dark modes via calcite-mode, updating styles automatically without affecting layout.
• Responsive behavior is built into Calcite layout components. Combine these adaptive behaviors with CSS to ensure layouts scale predictably across desktop, tablet, and mobile.

The dashboard layout sample illustrates GIS components integrated within a full dashboard layout. Maps, charts, and metrics are visually separated and styled into sections, demonstrating a combination of CSS layout, Calcite variables, and responsive design in practice.

Building a layout

When designing a web mapping application, the layout should reflect the story and workflow of the application. Begin by selecting a pattern that best fits the user’s needs and the type of content your application will display. Common layout patterns include:

• Single sidebar layout: One side panel for filters or tools; the main map occupies the remaining space.
• Dual panel layout: Panels on either side — for example, left for filters, right for legends or metrics.
• Docked panels with floating actions: Structured panels for controls, combined with floating buttons for drawing, selection, or navigation tools.
• Dashboard-style layout: Multiple sections for maps, charts, metrics, or summary panels. Each panel is self-contained but visually aligned.

Explore the sample layout applications built using JavaScript frameworks. You can also download the zips from jsapi-resources GitHub repository to run locally. Refer the get started page for guidance on using frameworks.

Plan your application regions

Before adding components, define the structural zones:

• Main content area: Typically an <arcgis-map> or <arcgis-scene>. This is the primary focus and should occupy the largest region.
• Secondary regions: For filters, legends, charts, or property inspectors. Panels can be collapsible or dockable depending on user workflows.
• Navigation and tool zones: Comprised of UI elements such as buttons, action bars, floating tools, and menus.
• Supplemental panels: More UI elements including dashboards, inset maps, or status displays.

A good practice is to map these regions on paper or in a wireframe first, identifying which regions are permanent, collapsible, or optional.

Use visual hierarchy

The layout should communicate priority and workflow:

• The map or scene should be be the focal point of the application as the primary content.
• Panels are sized relative to their importance — smaller for secondary tools, larger for primary controls.
• Group related tools together in Calcite blocks or panels to make the interface intuitive.
• Floating tools should be contextual and not block map interaction.
• Position headers, footers, and action bars in logical sections to reinforce hierarchy.

Components and their responsibilities

When building a web mapping application, choosing a consistent layout ensures predictable structure, usability, and scalability. Calcite Design System provides a set of layout components that define application regions, panel behavior, and navigation zones. Understanding the conceptual roles of each component helps you make deliberate layout decisions.

• calcite-shell: The application frame, which defines the overall structure of the application. It establishes primary regions such as slots for content areas, and headers. Think of it as the canvas on which your application lives. All other structural components are contained within the component.
• calcite-shell-panel: Useful for side regions. These panels live inside the shell and provide dockable or collapsible regions for controls, filters, legends, or supporting content. Panels are ideal for content that is important but secondary to the main map. They can be positioned at the start, end, top, or bottom.
• calcite-panel: A structured content container, which can be slotted inside shell panels or other layout regions to organize related content grouped within a panel using blocks. Use them to group controls, charts, tables, or descriptive information. They give a visual and functional hierarchy within a panel.
• calcite-action-bar: Provides compact navigation, such as quick access to tools like drawing, selection, or measurement. They are typically floating or docked, emphasizing immediate access rather than persistent structural presence.
• arcgis-map or arcgis-scene: Provide content, not layout. The map or scene is explicitly positioned within the layout, but it does not define the layout itself. Its size and position are determined by the shell and panels, keeping structure and functionality separate.

UI/UX layout considerations

Once an application’s layout is established, use additional Calcite components to provide context, guidance, and expected interactions. These elements ensure workflows are intuitive, important information is provided, and establish secondary tools without altering the core layout. For instance:

• Use links for navigation to documentation, external pages, or internal sections.
• Provide tooltips to deliver contextual hints for buttons, actions, or panels.
• Offer notices to communicate status.
• Enable advanced feature detail interactions or map-specific actions with popover.

Thoughtful use of components and their intent in an application ensures an interface is both functional and visually consistent. Read Building UI using calcite and components for more options on styling.

Best Practices

• Separation of concerns: Keep map logic separate from UI logic.

• Reactive updates: Use reactiveUtils or reactive properties for layer visibility changes.

• Accessibility: Calcite and SDK’s components are designed with accessibility in mind

• Responsive design: Use width-scale, height-scale, or CSS grid/flex for mobile-friendly layouts.

• Themes and modes: Control the visual identity of your application through themes and modes.

  • Mode defines the overall appearance context, such as light or dark. Switching calcite-mode-<light/dark> on the root container updates the visual mode across supported components.
  • Theme defines the brand expression layered on top of a mode, including colors, shadows, corner radius, and typography. A single theme can have both light and dark modes.

Visit Calcite components foundations to explore concepts while constructing layouts and building applications.