Last updated Feb 12, 2020

Board Tile Component

What if rendering a Trello board tile was as simple as adding a paragraph <p> or a link <a>? With the board tile component, its as simple as <trello-board-tile>!

Although we have the awesome board tile embed that lets you embed a Trello board tile into your page, it relies on a Trello user being logged in and isn't as flexible as some developers want it to be. If you are looking for a way to render native Trello board tiles in your project in a more flexible and controllable way, this card component is for you.

Live Example

Below is a live example of the board tile component:

And the code for the above ☝️is below 👇 – copy and paste it into an html file and give it a try!

1
2
<div id="board-tile-component-example">
  <!-- Board Tile Component Will Be Inserted Here -->
</div>

<script>
  const container = document.getElementById('board-tile-component-example');
  container.innerText = 'Loading...';

  const scriptSrc = window.customElements ? '/board-tile.min.js' : 'board-tile-polyfilled.min.js';
  const boardTileJs = document.createElement('script');
  boardTileJs.crossOrigin = 'anonymous';
  boardTileJs.src = 'https://p.trellocdn.com' + scriptSrc;

  boardTileJs.onload = function() {
    fetch('https://api.trello.com/1/board/dQHqCohZ?fields=name,prefs,url&structure=all&organization=true&organization_fields=displayName')
    .then(function(resp) {
      return resp.json();
    })
    .then(function(board) {
      const boardTileEl = document.createElement('trello-board-tile');
      boardTileEl.board = board;
      container.innerHTML = '';
      container.appendChild(boardTileEl);
    });
  }
  document.head.appendChild(boardTileJs);
</script>

Loading the Board Tile Component Script

The main component script you should include can be found here:

https://p.trellocdn.com/board-tile.min.js

However, if you want to support Edge, we recommend loading the polyfill that we have hosted at https://p.trellocdn.com/board-tile-polyfilled.min.js. Below is an example of how to load the polyfill to support Edge:

1
2
<!DOCTYPE html>
<html>
  <head>
    <!-- Your head content -->
    <script>
      const scriptSrc = window.customElements ? '/board-tile.min.js' : '/board-tile-polyfilled.min.js';
      window.cardComponentLoaded = new Promise(function(resolve) {
        const boardTileJs = document.createElement('script');
        boardTileJs.crossOrigin = 'anonymous';
        boardTileJs.src = 'https://p.trellocdn.com' + scriptSrc;
        boardTileJs.onload = resolve;
        document.head.appendChild(boardTileJs);
      });
    </script>
  </head>
  <body>
    <!-- ... -->
  </body>
</html>

This unusual script loading fork is a result of the Microsoft Edge browser not currently having built-in support for custom elements. We don't want to punish the other browsers which do have support so we only load the full polyfilled bundle when we detect that the browser needs it.

If your browser support matrix is limited to browsers that have native support for custom elements (see: https://caniuse.com/#feat=custom-elementsv1) you could simplify this to a single script tag:

1
2
<!-- If you don't support browsers like Edge -->
<script src="https://p.trellocdn.com/board-tile.min.js" crossorigin="anonymous"></script>

As with all of the scripts Trello hosts, when we announce updates on the changelog we will push changes to the staging versions of the component scripts first:

Rendering Board Tiles in Native Javascript

You can render a card by passing in an object that contains the card's field data to an element returned from the component. The only required field for a card is a name. For example, here is the minimal code required to render a card:

1
2
const boardTileEl = document.createElement('trello-card');

boardTileEl.board = {
  name: 'Name of board', // required
  url: 'https://trello.com/b/something',
}

document.body.appendChild(boardTileEl);

But that isn't very exciting! We support more fields from a board required to render a full-fledged board tile. Below is an example making use of all of the supported fields:

1
2

const boardTileEl = document.createElement('trello-board-tile');

boardTileEl.board = {
  id: "5abbe4b7ddc1b351ef961414",
  name: "Trello Platform Changelog",
  prefs: {
    backgroundImage: "https://trello-backgrounds.s3.amazonaws.com/SharedBackground/2560x1706/b72abeff4ceda56a0870bc1b12fdf5bd/photo-1426927308491-6380b6a9936f",
    backgroundImageScaled: [{
      width: 140,
      height: 100,
      url: "https://trello-backgrounds.s3.amazonaws.com/SharedBackground/140x100/fecfae755c1558bfb6bd881c8536d128/photo-1426927308491-6380b6a9936f.jpg"
    }, {
      width: 256,
      height: 192,
      url: "https://trello-backgrounds.s3.amazonaws.com/SharedBackground/256x192/f44dcced976019247eff9750a15843a4/photo-1426927308491-6380b6a9936f.jpg"
    }, {
      width: 480,
      height: 480,
      url: "https://trello-backgrounds.s3.amazonaws.com/SharedBackground/480x480/48ae6aa533b9c02c276f5ecdfd18e91d/photo-1426927308491-6380b6a9936f.jpg"
    }],
    backgroundTile: false,
    backgroundBrightness: "light",
    backgroundBottomColor: "#c8c9c5",
    backgroundTopColor: "#d5c2a8",
  },
  organization: {
    id: "538627f73cbb44d1bfbb58f0",
    displayName: "Trello Inc"
  },
  url: "https://trello.com/b/dQHqCohZ/trello-platform-changelog",
  structure: [1, 0, 3, 1, 3, 2, 2, 2, 3, 3]
};

document.body.appendChild(boardTileEl);

Additional Framework Support

In general, framework support for custom elements is quite good. That said, there may be some quirks to how to use a custom element in your framework of choice. We suggest taking a look at https://custom-elements-everywhere.com/ to see if there is anything special you would need to do in your framework to use Trello components.

Properties

To render the most complete board tile we recommend using the following API request:

https://api.trello.com/1/board/{idBoard}?fields=name,prefs,url&structure=all&organization=true&organization_fields=displayName

The following properties are specific to the component and can be explicitly set to control the display of the board tile:

Name	Value	Details
board	Object Default: `{ name: '' }`	The structure of the board.
footer	Boolean Default: true	Determines whether to render the Trello logo footer under the board.

Events

There are no custom events; however, normal DOM events can be used like usual. For example, if you wanted to add your own handler for a click on the board, and not have it open a new tab with the board URL you would use:

1
2
boardTileElement.addEventListener('click', (e) => {
  e.preventDefault();

  // ...
});