Mailing Labels Custom Widget
Mailing Label Widget Overview
This widget is designed to enhance mailing label management within the ArcGIS Experience Builder ecosystem. It offers seamless integration with map layers, advanced selection and drawing tools, and supports multiple label output formats including CSV and PDF.
Note: Requires install of jsPDF on client folder, running npm install jspdf
Note: Input service needs to be a Feature Layer (editing capabilities not required)
Developer Edition Configuration
End User Interaction
What Can This Widget Do?
Original capabilities (from core logic):
Select and configure map layers to use as data sources for labels.
Map fields to specific mailing fields (name, address, city, state, zip).
Draw shapes (point, polyline, polygon, rectangle, circle) to select areas for labels.
Generate labels in CSV and PDF formats with customizable label templates (Avery 5160–5164).
Font size options for printed labels.
Automatically disables Esri’s popups and highlights while active to focus on drawing and selection.
Clear selection areas and restore map behavior when the widget is closed.
Enhanced capabilities in this version:
Dynamic field mapping options that populate from selected layers.
Buffering options (distance and unit) for drawn geometries to expand selection areas.
Clear selection graphics and highlight management with fallback visualizations for feature selection.
Responsive label previews and customizable font size and label formats.
Error handling and messaging for failed queries or drawing operations.
Map view and layer management to handle disconnected or delayed map loading gracefully.
Interactive user messages (success, warning, error) displayed for actions like selection, generation, or errors.
Configuration Options
Map Widget Selection: Choose the map widget to connect to.
Layer and Field Mapping: Select a feature layer and assign fields to mailing label fields.
Geometry Selection: Enable selection by click, draw, or both; configure a buffer for drawn areas.
Label Format and Font: Choose from multiple Avery formats and set the font size.
Output Options: Generate mailing labels as CSV or open a print-ready PDF.
Changelog:
04/03/2026:
Implement idea from @AmyDuquesnoy about being able to add remove a selected feature after original selection area is drawn.
02/24/2026:
Integrate to grab selection from Custom Draw widget and pass to mailing labels (can be enabled/disabled in settings), See video at Advanced Draw Widget
02/12/2026:
Had a call come in from a realtor asking if they could select multiple parcels using a multipoint selection. Added multipoint selection as a pick option.
02/02/2026:
No longer maintaining 1.18 version.
Show original graphic vs buffer in different colors
- Add option to widget to remove duplicates and empty records (both on by default)
12/10/2025 (for 1.19 version only):
Theme Typography Update – All widget text now uses Experience Builder’s Theme Typography for consistent styling.
Accessibility Improvements – Added multiple WCAG-compliant updates across widgets for better usability and accessibility.
11/13/2025: Breaking changes between Developer Edition 1.18 and 1.19:
Upgrading ArcGIS Experience Builder Widgets from 1.18 to 1.19: Breaking Changes
Experience Builder 1.19 introduces two critical breaking changes that prevent widgets built for 1.18 from loading. First, the WidgetState enum has been removed from 'jimu-core', requiring developers to replace WidgetState.Opened with the string literal "OPENED" in widget lifecycle methods. Second, and more significantly, the jsx() function signature has changed to align with React 17+'s new JSX transform—children must now be passed as a children property within the props object rather than as separate function arguments. This means jsx('div', {props}, child1, child2) must be rewritten as jsx('div', {props, children: [child1, child2]}) throughout the entire render method. Every jsx call in your widget needs updating, with all child elements explicitly specified in the children prop (e.g., jsx('h2', { style: {...}, children: 'Title' })). While this is a substantial refactoring effort, it brings Experience Builder in line with modern React standards and is a one-time migration requirement for the 1.18 to 1.19 upgrade path.
I have posted both a 1.18 and a 1.19 version in this update to work on both versions.
10/14/2025: Resolved BUG integrating widget in Experience that uses multiple maps.
08/01/2025: Enhanced address type management and UI adaptation
- Added dual address type support: Widget now supports both Physical Mailing Address and Owner Address configurations with separate field mappings and optional separate data layers
- Added conditional UI display: Radio button selection automatically hides when only one address type is enabled in settings, providing a cleaner single-purpose interface
- Added automatic selection clearing: When switching between address types, any existing selections are automatically cleared to prevent data confusion, with user notification
07/23/2025: Tested widget on Developer Edition 1.18 that was released on 7/23/25 and widget functions as normal.
06/12/2025: Resolved bug that allowed for selection of up to 2,000 records but downloaded only 500. Limit now is 2,000 for both selection and CSV/PDF download.
05/28/2025: Automatic PDF Downloads with Smart Naming
@Brian_McLeer Thank you for making this widget. I am currently on version 1.18 and it is getting a fail to load once I publish or even preview it. Would you have any reason on why this is occurring?
@Brian_McLeer I am not getting any errors for my right click at all.
The mailing labels widget is still not working when it is nested in my sidebar within a section. If I have it floating in the map or even as a button, it works perfectly.
Greetings @Brian_McLeer,
I do not know if this helps or is most likely a separate thing but when I add the widget into an experience builder with two maps, it runs into a timeout error.
The image above contains a contrived minimal setup but reflects the same situation in one of the apps we are using the Mailing Label widget in.
@Brian_McLeer I have done a bit of testing. It appears when the widget searches for a map, it resolves. However, upon experimenting with it a bit more, it resolves to whatever map appears in some order. (In this case, from left to right with left taking priority over the right). I have attached images as references to both scenarios to illustrate this. LM being 'Light Map' and DM being 'Dark Map'. I could send dev tools console logs if that helps (not sure exactly how that would work in this medium).
Also, new look and updated features are great!
02/02/2026:
No longer maintaining 1.18 version.
Show original graphic vs buffer in different colors
- Add option to widget to remove duplicates and empty records (both on by default)
- Thank you for idea @KevinHitchcock
02/12/2026:
Had a call come in from a realtor asking if they could select multiple parcels using a multipoint selection. Added multipoint selection as a pick option.
04/03/2026:
Implement idea from @AmyDuquesnoy about being able to add remove a selected feature after original selection area is drawn.
