arcgis-print | References | ArcGIS Maps SDK for JavaScript

ESM

import "@arcgis/map-components/components/arcgis-print";

Inheritance:: ArcgisPrint→PublicLitElement

Since: ArcGIS Maps SDK for JavaScript 4.28

The Print component connects your application with a printing service to allow the map to be printed. It takes advantage of server-side, high-quality, full cartographic print functionality using the ExportWebMap service of ArcGIS, which can be configured with custom layout templates. One is provided that shows the map only, while another provides a layout with legend, etc. The Print component works with the print module, which generates a printer-ready version of the map.

The Print component uses the ArcGIS Online print service by default, but it can be configured to use a custom print service with the printServiceUrl property. The component can preserve map scale or map extent in the printout. By default, the map extent is preserved. Use TemplateOptions.scaleEnabled to preserve scale instead.

The Print component prints a localized date for all layouts except map-only. If using a custom print service, then customTextElements are supported for each print template. Values found there will be populated in the Print component under Advanced options. These values can be overwritten in the Print component UI, or programmatically using the templateCustomTextElements property.

For more information about printing with the MAP_ONLY layout, please see exportOptions.

Known limitations

See print for a detailed list of known limitations.

<arcgis-map item-id="45725ba7d9fb47a0925398919b13d1fa">
 <arcgis-print slot="top-right"></arcgis-print>
</arcgis-map>

// get a reference to the component
const components = document.querySelectorAll("arcgis-print");

const portal = new Portal({
 url: "https://user.maps.arcgis.com/sharing",
 authMode: "immediate",
 authorizedCrossOriginDomains: ["https://user.maps.arcgis.com"],
});

components.forEach((component) => {
 component.portal = portal;
});

Demo

Properties

Property	Attribute	Type
`allowedFormats`	`allowed-formats`	`Formats2`
`allowedFormatsForSaving`	`allowed-formats-for-saving`	`Formats \| undefined`
`allowedLayouts`	`allowed-layouts`	`Layouts`
`autoDestroyDisabled`	`auto-destroy-disabled`	`boolean`
`autoPopulateAuthor`	`auto-populate-author`	`boolean`
`excludeDefaultTemplates`	`exclude-default-templates`	`boolean`
`excludeOrganizationTemplates`	`exclude-organization-templates`	`boolean`
`exportedLinks`		`Collection<FileLink>`
`extraParameters`		`Record<string, any> \| null \| undefined`
`headingLevel`	`heading-level`	`HeadingLevel`
`hideAdvancedOptions`	`hide-advanced-options`	`boolean`
`hideHeader`	`hide-header`	`boolean`
`icon`	`icon`	`string \| undefined`
`label`	`label`	`string \| undefined`
`messageOverrides`		`Record<string, unknown> \| undefined`
`outSpatialReference`		`SpatialReference \| null \| undefined`
`portal`		`Portal`
`printServiceUrl`	`print-service-url`	`string \| null \| undefined`
`referenceElement`	`reference-element`	`ArcgisReferenceElement \| string \| undefined`
`showPrintAreaEnabled`	`show-print-area-enabled`	`boolean`
`state` readonly		`State`
`templateCustomTextElements`		`TemplateCustomTextElements \| null \| undefined`
`templateOptions`		`TemplateOptions`
`view`		`MapView \| null \| undefined`

allowedFormats

Property

Type: Formats2

Specify the print output file format(s) that the user can select based on the options available from the print service. This property can take a string value or an array of string values.

When this value is "all" (default value), all the print service formats are available to be used. When an array of string values is used, only those values that match the options available from the print service will be used. If none of the input string values match those available from the print service, allowedFormats will fallback to default behavior.

See also

TemplateOptions#format

Attribute: allowed-formats
Default value: "all"

Example

const print = new Print({
  view: view,
  printServiceUrl: url
});

print.viewModel.allowedFormats = ["jpg", "png8", "png32"];

view.ui.add(print, {position: "top-right"});

allowedFormatsForSaving

Property

Type: Formats | undefined

Specifies the print output file format(s) that the user can select when saving the exported map printout. This property can take a string value or an array of string values.

Attribute: allowed-formats-for-saving

allowedLayouts

Property

Type: Layouts

Specify the print output layout(s) that the user can select based on the options available from the print service. This property can take a string value or an array of string values.

When this value is "all" (default value), all the print service layouts are available to be used. When an array of string values is used, only those values that match the options available from the print service will be used. If none of the input string values match those available from the print service, allowedLayouts will fallback to default behavior.

See also

TemplateOptions.layout

Attribute: allowed-layouts
Default value: "all"

Example

const print = new Print({
  view: view,
  printServiceUrl: url
});

print.viewModel.allowedLayouts = ["a3-landscape", "a3-portrait"];

view.ui.add(print, {position: "top-right"});

autoDestroyDisabled

Property

Type: boolean

If true, the component will not be destroyed automatically when it is disconnected from the document. This is useful when you want to move the component to a different place on the page, or temporarily hide it. If this is set, make sure to call the destroy() method when you are done to prevent memory leaks.

Attribute: auto-destroy-disabled
Default value: false

autoPopulateAuthor

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.0

Indicates whether to automatically populate the author field in the print layout advanced options with the username of the current portal user.

This only takes effect if there is a portal with a signed-in user assigned to the portal property.

Attribute: auto-populate-author
Default value: false

excludeDefaultTemplates

Property

Type: boolean

Indicates whether or not to include defaultTemplates.

Attribute: exclude-default-templates
Default value: false

excludeOrganizationTemplates

Property

Type: boolean

Indicates whether or not to include templates from an organization's portal.

Attribute: exclude-organization-templates
Default value: false

exportedLinks

Property

Type: Collection<FileLink>

Since: ArcGIS Maps SDK for JavaScript 4.33

The collection of links exported from the Print component.

extraParameters

Property

Type: Record<string, any> | null | undefined

This option allows passing extra parameters (in addition to templateOptions) to the print (export webmap) requests.

headingLevel

Property

Type: HeadingLevel

Indicates the heading level to use for the "Exported files" text where users can access the exported map printout. By default, this text is rendered as a level 3 heading (e.g. <h3>Exported files</h3>). Depending on the component's placement in your app, you may need to adjust this heading for proper semantics. This is important for meeting accessibility standards.

Attribute: heading-level
Default value: 3

hideAdvancedOptions

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.0

Indicates whether the advanced options section in the Print component UI is hidden.

Attribute: hide-advanced-options
Default value: false

hideHeader

Property

Type: boolean

Indicates whether the component's header is hidden.

Attribute: hide-header
Default value: false

icon

Property

Type: string | undefined

Icon which represents the component. Typically used when the component is controlled by another component (e.g. by the Expand component).

See also

Calcite Icons

Attribute: icon
Default value: "print"

label

Property

Type: string | undefined

The component's default label.

Attribute: label

messageOverrides

Property

Type: Record<string, unknown> | undefined

Replace localized message strings with your own strings.

Note: Individual message keys may change between releases.

outSpatialReference

Property

Type: SpatialReference | null | undefined

Since: ArcGIS Maps SDK for JavaScript 4.33

The spatial reference used to render the printed map on the server.

portal

Property

Type: Portal

It is possible to search a specified portal instance's locator services. Use this property to set this ArcGIS Portal instance to search. This is especially helpful when working with a custom template.

If this property is set, it is not necessary to set the printServiceUrl property.

See also

CustomTemplate

printServiceUrl

Property

Type: string | null | undefined

The URL of the REST endpoint of the Export Web Map Task. Defaults to the ArcGIS Online print service if this property is not specified. If the portal property is set, this property will use the portal's print service URL.

Attribute: print-service-url

referenceElement

Property

Type: ArcgisReferenceElement | string | undefined

By passing the id of the Map or Scene component into this property, you can position components from the @arcgis/map-components package anywhere in the DOM while still maintaining a connection to the Map or Scene.

See Associate components with a Map or Scene component.

Attribute: reference-element

showPrintAreaEnabled

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 4.30

The initial state of the print area toggle in the Print component UI. When set to true, the print area toggle is enabled by default. When set to false, the print area toggle is disabled by default.

See also

Print component

Attribute: show-print-area-enabled
Default value: false

state

readonly Property

Type: State

The state of the Print component.

Default value: "disabled"

templateCustomTextElements

Property

Type: TemplateCustomTextElements | null | undefined

An object containing an array of customTextElements name-value pair objects for each print template in a custom print service. Use this property to update the text for custom text elements on the page layout.

The Print component calls the Get Layout Templates Info task on the GPServer to discover possible customTextElements values for each template. The name of the task must match Get Layout Templates Info, templates must be published with customTextElements, and values must be strings. Values found there will be populated in the Print component under Advanced options. These values can be overwritten in the Print component UI, or programmatically using this property. To list all print templates available on the print service to see see which templates were published with customTextElements, use the effectiveTemplateCustomTextElements property.

Example

const printViewModel = new PrintViewModel({
   view: view,
   // specify your custom print service
   printServiceUrl: "",
   // `customTextElements` are defined per print template
   // this example has one template with `customTextElements`
   templateCustomTextElements: {
      // if there were more applicable templates, then we would
      // create another object with the template name containing
      // an array of more name-value pairs
      "Portrait_TextElements": [
          // the possible values are defined in the print service
          { "headquarters": "Tampa, Florida" },
          { "division": "NFC South" },
          { "founded": "1976" }
      ]
   }
 });

templateOptions

autocast Property

Type: TemplateOptions

Since: ArcGIS Maps SDK for JavaScript 4.33

Defines the layout template options used by the Print component to generate the print page.

view

Property

Type: MapView | null | undefined

The view associated with the component.

Note: The recommended approach is to fully migrate applications to use map and scene components and avoid using MapView and SceneView directly. However, if you are migrating a large application from widgets to components, you might prefer a more gradual transition. To support this use case, the SDK includes this view property which connects a component to a MapView or SceneView. Ultimately, once migration is complete, the arcgis-print component will be associated with a map or scene component rather than using the view property.

Methods

Method	Signature
`addPortalTemplate`	`addPortalTemplate(portalItem: PortalItem): Promise<void>`
`componentOnReady` inherited	`componentOnReady(): Promise<this>`
`destroy`	`destroy(): Promise<void>`

addPortalTemplate

Method

Signature: addPortalTemplate (portalItem: PortalItem): Promise<void>

Since: ArcGIS Maps SDK for JavaScript 5.0

Adds a portal item to a collection of browse templates available in the Print component UI.

Parameters

Parameter	Type	Description	Required
portalItem	`PortalItem`	The portal item to add.

Returns: Promise<void>
Resolves when the portal template has been added.

componentOnReady

inherited Method

Signature: componentOnReady (): Promise<this>

Inherited from: PublicLitElement

Creates a promise that resolves once the component is fully loaded.

Returns: Promise<this>

Example

const arcgisPrint = document.querySelector("arcgis-print");
document.body.append(arcgisPrint);
await arcgisPrint.componentOnReady();
console.log("arcgis-print is ready to go!");

destroy

Method

Signature: destroy (): Promise<void>

Permanently destroy the component.

Returns: Promise<void>

Events

Name	Type
`arcgisBrowseTemplatesChange`	CustomEvent<CollectionChangeEvent<CustomTemplate>>
`arcgisComplete`	CustomEvent<CompleteEvent>
`arcgisPropertyChange`	CustomEvent<{ name: "state"; }>
`arcgisReady`	CustomEvent<void>
`arcgisSaveAs`	CustomEvent<FileLink>
`arcgisSubmit`	CustomEvent<SubmitEvent>

arcgisBrowseTemplatesChange

Event

arcgisBrowseTemplatesChange: CustomEvent<CollectionChangeEvent<CustomTemplate>>

Since: ArcGIS Maps SDK for JavaScript 5.0

Emitted when the collection of browse templates changes.

arcgisComplete

Event

arcgisComplete: CustomEvent<CompleteEvent>

Emitted when the component is complete.

arcgisPropertyChange

Event

arcgisPropertyChange: CustomEvent<{ name: "state"; }>

Emitted when the value of a property is changed. Use this to listen to changes to properties.

arcgisReady

Event

arcgisReady: CustomEvent<void>

Emitted when the component associated with a map or scene view is ready to be interacted with.

arcgisSaveAs

Event

arcgisSaveAs: CustomEvent<FileLink>

Since: ArcGIS Maps SDK for JavaScript 5.0

Emitted when the user saves an exported map printout.

arcgisSubmit

Event

arcgisSubmit: CustomEvent<SubmitEvent>

Emitted when the component is submitted.