ArcGIS Maps SDK for JavaScript

Browsing Related Records with the ArcGIS API for JavaScript

Relationships are essential in life whether they are personal with family or friends, work related with colleagues, etc. The same goes for relationships within your geographical data. Version 4.25 of the ArcGIS API for JavaScript (ArcGIS JS API) introduced a way to browse your data’s relationships through a feature’s pop-up. This is done through the RelationshipContent element. The FIFA World Cup Qatar 2022 tournament has begun, so let’s explore an application that browses FIFA World Cup relationships!

Related Records App
World countries and FIFA World Cup highest capacity stadiums from 1930-2018.

What are relationships within ArcGIS?

Let’s begin by defining what relationships are within the ArcGIS System. Relationships provide a way to associate features and records with one another without being in the same layer or table while helping to enforce data integrity. The primary motivation for modelling geographic (or any data) with relationships is to support cardinality. A relationship’s cardinality specifies the number of objects in the origin class that can relate to a number of objects in the destination class. For example, a country may have one, none, or many past or present FIFA stadiums.

Relationships can be created between different data sources, such as:

To learn more about relationships and why they are important, see the ArcGIS Pro documentation.

Creating relationships

To browse related records in web applications, relationships need to be created prior to publishing your data using the Create Relationship Class tool in ArcGIS Pro.

For the World Cup app, I used the ArcGIS Living Atlas countries* layer and created:

Below is a table showing the details of the relationships created using the Create Relationship Class tool in ArcGIS Pro between those layers/table:

Relationship information
Table showing the relationships between the FIFA World Cup data.

In this blog, we will focus on how to configure the pop-up to display the second relationship from the table above: the Countries layer and the World Cup Winners 1930-2018 table.

After creating the relationships in ArcGIS Pro, confirm all layers/tables participating in the relationship are in the map and publish everything to ArcGIS Online. Note, viewing related records within pop-ups is only supported for hosted layers starting at version 4.25.

* It must be noted that this demonstration only shows current nations. Former countries like Yugoslavia which came fourth in 1930 and 1962 are not shown.

Related Records and the ArcGIS JS API

Once the data is published, the app can be configured to display the related information with the new PopupTemplate content type, RelationshipContent. To display information from the World Cup Winner 1930-2018 table data within the Countries layer’s pop-up, relationship content needs to be added to the content property on the countries layer pop-up template.

Add Related Layers/Tables to the Map

Prior to adding the relationship content, the layers and tables participating in the relationship must be added to the map. If the related layers/tables are missing, an error message will appear in the UI of the pop-up:

Error-Relationship not found in the map.
Error message when the relationship is not found in the map.

The code below shows how to add the countries layer and the World Cup Winner table with a specific field list configured in its pop-up:

// Create the world countries layer and add a renderer.
const countriesLayer = new FeatureLayer({
  url: "",
  title: "World Countries Generalized",
  // ... other layer properties
// Add the countries layer to the map.
// Create the non-spatial table containing FIFA World Cup standings and stats.
const winnersTable = new FeatureLayer({
  url: "",
  title: "Country Statistics",
  popupTemplate: {
    title: "FIFA World Cup {Year} Standings in {Host}",
    outFields: ["*"],
    // Add the fields to the FieldInfos
    fieldInfos: [
        fieldName: "First"
        fieldName: "Second"
        fieldName: "Third"
        fieldName: "Fourth"
        fieldName: "TopScorer",
        label: "Top scorers and number of goals"
        fieldName: "BestPlayerAward",
        label: "Best player award"
    content: [
      // Add FieldsContent via autocasting
        type: "fields"
// Load the non-spatial table and add it to the map's tables.
winnersTable.load().then(() => {

Add Relationship Content

Once the layers are added and the statistics table pop-up template is configured, the relationship content can be created with the required properties:

Relationships Layer Resource
Relationship information for countries layer on the service.

The code below creates a new RelationshipContent object using autocasting and adds the object to the pop-up template content:

countriesLayer.popupTemplate.content = [
    type: "relationship",
    // Relationship ID on the feature service is 1
    relationshipId: 1,
    title: "Victories",
      "Every FIFA World Cup tournament {COUNTRY} has won first place
       in from 1930-2018 ordered by most recent.",
    displayCount: 2,
    // Orders the related records by the year the tournament was held
    // by most recent to oldest
    orderByFields: [
        field: "YEAR",
        order: "desc"

Once added to the pop-up template, the related records of the selected feature can be explored within the pop-up! The images below show Brazil’s pop-up and what the pop-up looks like when selecting a related feature. In this case, Brazil’s victory in the 2002 world cup hosted in South Korea and Japan was selected from the list of related records:

Popup chart
User interface of origin feature and destination feature.

Note that the pop-up template that was configured for the related table displays within countries pop-up. It’s that simple to add related records within pop-ups using the ArcGIS JS API!

But wait.. there is more content!

Multiple relationships and/or different types of content can be added to the pop-up template depending on the story that’s being told through data exploration. In the completed FIFA World Cup app, the countries pop-up template is configured with custom content that queries the related table for statistics and both relationships in the table above.

Brazil Pop-up
Pop-up for Brazil that contains CustomContent and RelationshipContent for both relationships.

Best practices

What’s Next?

Viewing related records is just the beginning of what is to come. In future releases of the ArcGIS API for JavaScript, we plan to support:


Supporting related records in feature pop-ups is quick and easy with the ArcGIS JS API and opens up so many possibilities for data exploration in your applications.

If you’d like to play around with the code shown in this blog, or would like to browse historic FIFA World Cup statistics, check out the live application and source code. If soccer(futbol) is not your thing, don’t worry. Take a look at this sample that uses relationships to link Californian administrative areas to wildfires.

About the author

Lauren is a Product Engineer on the ArcGIS Maps SDK for JavaScript team in Redlands, CA with her work focusing primarily on popups and security. She has worked at Esri for over 7 years and enjoys helping/supporting geo-developers utilize the ArcGIS API for JavaScript into their awesome applications.

Notify of
Inline Feedbacks
View all comments

Next Article

Deprecation Notice for ArcGIS GeoAnalytics Server

Read this article