A custom Experience Builder widget is a React/TypeScript component built with the ArcGIS Experience Builder Developer Edition SDK and dropped into your own widget folder. You build one when the configurable widgets cannot express your workflow — bespoke forms, cross-system look-ups, custom charts, Arabic-first layouts or approval steps — and you want it to stay inside the same portal app, with the same login and the same data connections.
Widgets are delivered as source in your repository, versioned against a specific Experience Builder release, with a documented upgrade path so your team can rebuild them after each portal upgrade.
What problem does this solve?
ArcGIS Experience Builder covers a surprising amount of ground without code: maps, lists, filters, charts, dashboards-style layouts, and a designer that non-developers can use. Teams get eighty per cent of a public portal or an internal operations screen in a few days. Then the last twenty per cent stops the project. The requirement is a submission form that writes to three layers at once and calls the asset register for validation, or a panel that shows an asset's open work orders from IBM Maximo next to its inspection history, or a bilingual approval step where a supervisor signs off a field report. None of that is a setting.
The usual workarounds make it worse. Embedding an external web page in an iframe breaks the single sign-on, the shared selection state and the responsive layout, and it produces two applications to maintain instead of one. Chaining several configured widgets to fake one workflow leaves users clicking through panels that do not share context. Rewriting the whole thing as a standalone application with the ArcGIS Maps SDK for JavaScript is a legitimate option, but it throws away the designer, the theming, the printing, the mobile layouts and the portal item management that Experience Builder already gives you.
There is also an upgrade trap. Experience Builder Developer Edition is versioned against your ArcGIS Enterprise release. A widget written by a contractor against version 1.x, with no source in your repository and no build pipeline, becomes an obstacle at the next portal upgrade — and portals do get upgraded, on a schedule set by your security team rather than by the GIS team.
How the solution works
A custom widget is a React and TypeScript component built with the Experience Builder Developer Edition SDK and placed in your own client/your-extensions/widgets/ folder. It participates in the app exactly like an Esri widget: it receives configured data sources, reads and publishes selection messages, inherits the theme, respects the responsive layout, and runs under the portal identity of the signed-in user. You also get a settings panel, so the widget stays configurable in the designer instead of being hard-coded to one map.
Custom themes are the smaller sibling of the same mechanism. A theme is a folder of variables and styles — colour ramps, typography, spacing, button shapes, logo placement — that applies to every widget in the app, including Esri's. For UAE government work this is where entity brand guidelines, Arabic typography and right-to-left behaviour get handled once rather than per screen. Swedish Technology delivers widgets and themes as source in your repository, with a build script, a version matrix against your ArcGIS Enterprise release, and a written upgrade procedure so that a portal upgrade is a rebuild and a regression test, not a rescue project.
- 1Input A user opens the Experience Builder app in a browser and signs in with the portal identity (OAuth, SAML or Entra ID SSO). The app loads its configuration, including the widgets placed by the designer.
- 2Capture The custom widget receives the data sources configured for it — feature layers, web maps, tables — and captures user input: map clicks, sketches, form fields, uploaded photos or a scanned tag ID.
- 3Processing Validation and business logic run in the widget: required fields, domain and format checks, geometry checks against reference layers, and calculated values. Heavier processing is delegated to a geoprocessing service.
- 4Integration Where the workflow needs another system, the widget calls your integration service over REST with the user's token; the service brokers SAP, Maximo, Odoo, RFID/RTLS or document platforms and keeps their credentials server-side.
- 5Action The widget applies edits through the feature service (applyEdits), publishes a message so the map and other widgets react, and shows the result — a created work order number, a validation failure, a routed approval.
- 6Reporting Submissions are written to a log layer or table, dashboards and reports read from the same services, and printed outputs are produced through the portal print service or a custom report endpoint.
Reference architecture
Keep the widget presentational and thin, and put rules and integrations where they can be tested and reused by other clients.
| Layer | What it contains |
|---|---|
| Presentation (widget) | React + TypeScript component built with the Experience Builder Developer Edition SDK; jimu-core and jimu-arcgis for data sources, messages and the map view; a settings component so the widget stays configurable in the designer. |
| Theme | Custom theme folder with variables (colours, typography, spacing, radii), component overrides and right-to-left rules; applied app-wide so Esri widgets match the entity brand. |
| Domain / rules | Shared TypeScript module (or a geoprocessing service) holding validation and calculation rules with unit tests, so the same logic can back a widget, an ArcGIS Pro add-in and a scheduled script. |
| Integration service | Small API (ASP.NET Core, Node or Python) that brokers calls to SAP, Maximo, Odoo, RTLS platforms and document systems; handles retries, rate limits, mapping and audit logging. |
| Data & services | ArcGIS Enterprise portal items, hosted or referenced feature services, geoprocessing services, print and geocoding services; editor tracking and attachment rules on the editable layers. |
| Identity & security | Portal OAuth 2.0 / SAML SSO for the user; layer and item permissions enforced server-side; service credentials in a vault; TLS and reverse proxy in front of the web server. |
Deployment options: Widgets and themes are built with the Developer Edition toolchain and either deployed with a Developer Edition app on your own web server, or packaged and uploaded to ArcGIS Enterprise so the widget appears in the portal's Experience Builder for app authors. Both run on-premise or in a UAE-region private cloud; an air-gapped build is possible because the toolchain and dependencies can be mirrored internally.
Key capabilities
Custom data-entry and inspection forms
Field and office users submit structured records with validation, photos and geometry in one panel instead of three widgets.
availableCross-system look-up panels
Selecting an asset on the map shows its ERP or maintenance records beside its GIS attributes.
custom developmentCustom charts and KPI panels
Managers see the exact indicator definitions used in their reporting, not a generic chart type.
availableApproval and routing steps
A submission can be reviewed, returned or approved inside the same app, with status written back to the layer.
custom developmentCustom theme with entity branding
The app matches the organisation's visual identity, including Arabic typography and right-to-left layout, in one place.
availableLive position and sensor panels
Operations staff see RTLS or IoT positions and alerts in the same screen as the base map.
custom developmentBilingual (Arabic / English) widgets
Users switch language without a second application, with correct mirroring of panels and controls.
availablePrinting and export to report templates
Users produce a formatted PDF for a permit, inspection or committee pack directly from the app.
custom developmentIntegrations
The widget never holds credentials for another system. All non-ArcGIS calls go through an integration service that authenticates the user's token, maps fields and writes an audit trail.
| System | Integration point & data exchanged | Direction |
|---|---|---|
| ArcGIS Enterprise portal | Web maps, feature services, groups and item permissions; the widget uses the configured data sources rather than hard-coded URLs. | bi-directional |
| SAP PM / S/4HANA | Functional location and equipment look-up, notification creation from a selected feature, status shown in the panel (OData). → ArcGIS – SAP Integration (PM/EAM, S/4HANA) | bi-directional |
| IBM Maximo | Work-order and asset data displayed next to the map, inspection results posted back through Maximo REST/OSLC. → ArcGIS – IBM Maximo Integration | bi-directional |
| RFID / RTLS platform | Live and last-seen positions, geofence alerts and tag-to-feature bindings shown in a custom panel. → ArcGIS RTLS & RFID Integration: Live Location in GIS | inbound |
| Document & correspondence system | Attach or open permits, drawings and reports for the selected feature without leaving the app. → Document Management & Correspondence System | outbound |
| Workflow automation platform | Submissions raise tasks and approvals in the organisation's workflow engine and return status to the map. → Primavera P6 – Project Management | bi-directional |
Industry use cases
Municipality — public services
A bilingual public reporting app where residents place a point, upload a photo and submit a complaint that is validated, deduplicated against nearby open cases and routed to the right department.
Roads & transport authority
An internal operations screen where a supervisor selects a road section and sees inspection history, pavement condition scores and open maintenance work orders in one panel.
Utilities
An outage and asset panel that combines network features with SCADA or ERP status, with a custom widget for isolating a section and generating a notification.
Facilities & real estate
A floor-plan viewer with a custom booking or work-request widget, styled to the landlord's brand through a custom theme.
Security & industrial sites
A situational-awareness screen combining map layers, live RTLS positions and camera analytics alerts, with a custom acknowledgement widget.
UAE & GCC considerations
Most UAE and GCC government entities run ArcGIS Enterprise on-premise or in a locally hosted private cloud, so an Experience Builder app and its custom widgets stay inside the same network and data-residency boundary — no data leaves the environment, and the integration service can sit on the same segment. Arabic is rarely optional: entities expect the interface, validation messages, printed outputs and number and date formats to work in Arabic and English, with right-to-left mirroring handled by the theme rather than patched per widget. Procurement usually asks for source code delivery, a hand-over package in both languages, and evidence that the solution survives the entity's ArcGIS Enterprise upgrade cycle, so the version matrix and rebuild procedure belong in the deliverables from the start.
Implementation approach
- 1Discovery (1–2 weeks) Walk through the screens users actually need, list what standard widgets already cover, and identify the specific gaps. Confirm the ArcGIS Enterprise version and the matching Experience Builder Developer Edition release.
- 2Decision Written recommendation per gap: configure, custom widget, custom theme, geoprocessing service, or a separate application. Some requirements disappear once the data model is fixed.
- 3Design Wireframes for the widget and its settings panel, bilingual copy, theme tokens, integration contract (fields, directions, error handling) and the security model.
- 4Environment setup Developer Edition installed and registered with the portal, source repository, build pipeline, and a test portal or a copy of the production items.
- 5Build & test Iterative sprints; unit tests for rules; accessibility and RTL checks; testing on the browsers and screen sizes the entity supports, including tablets used in the field.
- 6Pilot A small user group runs the app on real work for 2–4 weeks; performance checks against production data volumes; feedback loop.
- 7Deployment Widget and theme packaged and deployed to the portal or to the Developer Edition server, with rollback steps and a smoke-test checklist.
- 8Hand-over & upgrade plan Source, build instructions, admin and user guides, recorded training, and a documented procedure for rebuilding against the next Experience Builder release.
Security & deployment
The widget runs in the user's browser under the portal identity, so existing item, layer and field-level permissions still apply — a custom widget cannot show data the user is not entitled to see, provided the services are secured properly rather than shared publicly. Calls to non-ArcGIS systems go through the integration service, which validates the user's token, holds system credentials in a vault and writes an audit record for every read and write. Content Security Policy, TLS termination at a reverse proxy and dependency scanning of the widget's npm packages are part of the build. For classified or air-gapped environments the Developer Edition toolchain and its dependencies are mirrored internally and the app is deployed from an internal artefact store.
Limitations & prerequisites
- Custom widgets require Experience Builder Developer Edition and a build step; they cannot be authored in ArcGIS Online's or the portal's browser-based designer alone.
- Widgets are versioned against a specific Experience Builder / ArcGIS Enterprise release and normally need a rebuild and regression test at each portal upgrade — budget for it every cycle.
- Development needs React and TypeScript skills plus familiarity with the jimu framework; it is not a task for a GIS analyst without developer support.
- The widget runs in the browser, so heavy geoprocessing must be pushed to a geoprocessing service or a backend job rather than done client-side.
- Custom themes affect all widgets in the app, including Esri's; aggressive style overrides can break at the next release and should be limited to documented theme variables.
- Integrations depend on SAP, Maximo, Odoo or RTLS API access being granted by their owners, and on realistic response times — a slow ERP call makes the whole panel feel slow.
- Truly offline field use is outside Experience Builder's scope; that needs ArcGIS field apps with offline maps or a dedicated mobile application.
Configure vs custom widget vs custom application
Choose the lightest option that meets the requirement, and be explicit about the upgrade cost you are accepting.
| Criterion | Configured Experience Builder | Custom widget (Developer Edition) | Custom app (Maps SDK for JavaScript) |
|---|---|---|---|
| Who can build it | GIS analyst / app author | Web developer (React + TypeScript) | Web developer team |
| Bespoke forms and workflows | Limited to widget settings | Yes, full control inside the app shell | Yes, full control |
| Reuse of Esri widgets and layout | Full | Full — the widget joins the same app | None; rebuild everything |
| Calls to SAP / Maximo / RTLS | Not practical | Through the integration service | Through the integration service |
| Branding and Arabic RTL | Standard themes | Custom theme, app-wide | Whatever you build |
| Upgrade effort | Low — Esri maintains widgets | Rebuild and test per release | Independent of Experience Builder, but you own all of it |
| Time to first version | Days | Weeks | Months |
| Best for | Dashboards, viewers, simple submissions | One or two gaps in an otherwise standard app | Public-facing products with a distinct user experience |
In practice most projects are a configured app with one or two custom widgets and a custom theme. If you find yourself writing five widgets that replace every Esri one, that is the signal to evaluate a standalone application instead.
FAQ
The number of distinct screens and states, the complexity of validation rules, how many external systems are called, whether it must be bilingual with right-to-left support, and the level of testing and documentation required. A single look-up panel is days of work; a multi-step submission with approvals and two integrations is several weeks.
Discovery and design usually take 2–3 weeks. A first usable widget takes 3–8 weeks depending on integrations, and pilot plus roll-out adds another 3–4 weeks. Custom themes are normally a few days once brand guidelines are available.
Yes, for custom widgets and custom themes. The browser-based designer in ArcGIS Online or Enterprise can only place and configure widgets that already exist. Developer Edition is downloaded from My Esri under your existing licensing.
Yes. Developer Edition apps run on your own web server against an on-premise ArcGIS Enterprise portal, and the integration service can sit in the same network segment. Air-gapped builds work when the npm dependencies are mirrored internally.
Custom widgets are tied to an Experience Builder version, so an upgrade means installing the matching Developer Edition, rebuilding the widget, fixing any framework API changes and running a regression test. With source and a build pipeline in your repository this is usually days, not a rebuild.
Yes, through the feature service using the signed-in user's permissions. Field-level and editor-tracking settings on the layer still apply, and we normally add a validation step and a log table so submissions can be audited.
Text is externalised into translation files, the layout mirrors through the theme's right-to-left rules, and numbers, dates and printed outputs are formatted per locale. Arabic is designed in from the first screen rather than retrofitted, because mirroring a layout afterwards is the expensive path.
You own the source, the repository and the build pipeline; they are handed over with documentation and training. Swedish Technology can maintain the widgets under a support agreement, including the rebuild at each portal upgrade, or step back once your team is comfortable.
Stuck between a configured app and a full custom portal?
Describe the screen you cannot build and send a sketch or screenshot. We reply with a written view: configure, custom widget, custom theme or separate application — with effort, upgrade cost and risk.
Request an Experience Builder AssessmentSources & evidence
- Esri — ArcGIS Experience Builder Developer Edition guide — official widget development guide
- Esri — Experience Builder: extend with custom widgets and themes
- Esri — ArcGIS Maps SDK for JavaScript
- Esri — ArcGIS Enterprise portal security and authentication
- W3C — Web Content Accessibility Guidelines (WCAG) overview
Vendor and product names are trademarks of their respective owners; references are for technical context and do not imply partnership, certification or endorsement unless stated on the vendor's official pages.