▾
To build a web mapping application, ArcGIS Maps SDK for JavaScript
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. Explore layout patterns and layout code samples demonstrating Shell-based layouts with accompanying navigation, side panels, and a main content region. The Calcite simple layout, and map with sidebar pages show these patterns in use.
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.
For map or scene behavior inside those regions, use Calcite’s map with overlay sample and the SDK’s general focused map and scene samples.
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 Calcite dashboard sample illustrates how maps, charts, and metrics can be visually separated and styled into sections, demonstrating a combination of CSS layout, Calcite variables, and responsive design in practice.
Building a layout
Choose a layout that supports what users need to do and the content they need to see. Common patterns include:
- Single sidebar: Place filters or tools in one side panel, with the map in the remaining space.
- Dual panels: Place a panel on each side of the map, such as filters on one side and a legend or metrics on the other.
- Docked panels and floating actions: Use docked panels for controls and floating buttons for tools such as drawing, selection, and navigation.
- Dashboard: Arrange maps, charts, metrics, and summaries in separate, aligned regions.
For a list-and-details layout, use calcite-flow to show an item’s details after a user selects it. This keeps the application shell in place. See the gallery detail sample.
Explore the Calcite layout samples for complete UI compositions, and use the get started page for framework-specific SDK setup.
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 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-maporarcgis-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.