Fetching Data

Last updated 3 months ago

Features aren't very useful if they're static. A Datasource is a URL your component can retrieve data from and use it to dynamically generate its UI.

Adding Datasources

You may add one Datasource per feature, using the Datasources panel in the left tool sidebar of the Mason Builder. Each Datasource must have a URL that responds to a GET request with an application/json payload in the response body. Data will be fetched from your Datasource when your component is constructed.

Dynamic Parameters

You may inject dynamic header or query parameters, like authorization tokens, at runtime by using the willFetchData callback prop. These values will be merged with the values you set in the Mason Builder, with the values here taking precedence in the event of a conflict.

import React from 'react';
import { Feed } from 'mason-library';
class MyFeed extends React.Component {
render() {
const { search, token } = this.props;
return <Feed
willFetchData={({ url, headers, queries }) => {
return {
headers: { 'Authorization': token },
queries: { 'search': search }
}} />;

Your function will receive as its sole argument an object with the following structure

url: 'https://example.test',
headers: {
'Content-Type': 'application/json'
queries: {
foo: 'bar'

You must return an object, if you have no modifications return an empty object.

Dynamic Parameters with HTML

Because events are immutable, you cannot provide dynamic parameters if you're embedding your feature as HTML. You may add an event subscriber to be notified when your feature will fetch data, however.

<mason-feed id="feed" data-id="YOUR_COMPONENT_ID"></mason-feed>
<script type="text/javascript">
const feedNode = document.getElementById('feed');
feedNode.addEventListener('mason.willFetchData', function(event) {
//show a loading notification

Providing Data at Runtime

In some cases you may want to provide data directly to a feature rather than having it fetched from a Datasource. For example, user generated content you want to display prior to submission. To accomplish this, you can provide an object as a data prop directly to your feature and map parts of it to specific UI elements.

To display a dynamic value in your UI, you must tell your Mason feature where to find it in the data you'll provide at runtime. You accomplish this by providing the dot-separated string path to the value to the Mason Builder.

Consider the below object you want to pass at runtime

cart: {
products: [{
id: 123,
name: 'Acme T-Shirt',
thumbnail: 'https://example.test/products/123.jpg',
total: '$194.72',
shipping: '$7.00'

To render the value in the total key, $194.72, as a child of a DOM element, select the desired element and enter cart.total in the Data Mapping section of the right tool sidebar of the Mason Builder.

You may also map images. If you provide a Data Mapping path to an image element, Mason will map the value found at the path to the src property. In the example above, map cart.products.0.thumbnail to an image to display the thumbnail.

Note that data provided at runtime will take precedence over data from a Datasource. So if your Datasource's response contains a value at cart.total it will be overwritten by your provided data.