Embedded Timelines

Updated on Fri, 2014-02-07 13:59

English | 日本語

Overview

Embeddable timelines make it easy to syndicate any public Twitter timeline to your website with one line of code.

Just like timelines on twitter.com, embeddable timelines are interactive and enable your visitors to reply, Retweet, and favorite Tweets directly from your pages. Users can expand Tweets to see Cards inline, as well as Retweet and favorite counts. An integrated Tweet box encourages users to respond or start new conversations, and the option to auto-expand media brings photos front and center.

These new timeline tools are built specifically for the web, mobile web, and touch devices. They load fast, scale with your traffic, and update in real-time. Create your own embedded timeline from your widgets settings page on twitter.com.

Available Timelines

You can embed a timeline for Tweets from an individual user, a user's favorites, Twitter lists, or any search query or hashtag.

User

You may create an embedded timeline for any public Twitter user. The example posted above is the public user timeline for @twitterapi. Each user timeline includes a follow button in the header, allowing website visitors to follow the account with one-click. There's a Tweet box in the footer, enabling visitors to Tweet directly to the user without leaving the page.

Here's @twitterapi's timeline embedded directly into this page:

Custom Timelines

Custom Timelines are collections of tweets in any order, as curated by Twitter users. Embedding these custom timelines lets you share your timelines with the world.

Favorites

Like the user timeline, a favorites timeline may be created for any public Twitter user, and displays that user's favorited Tweets.

List

The list timeline shows Tweets from a specific list of users. The header of the list widget contains the list name, description, and links to the list creator's profile. Retweets by members of the list are included in the timeline. To create a list timeline you must have either created that list yourself, or subscribe to it.

Search and #hashtag

You may create a search timeline for any query or #hashtag. Searches for a single #hashtag feature a simplified header section, and a “Tweet #hashtag” Tweet box in the footer so that visitors can easily contribute to the conversation directly from your page. Clicking on the #hashtag in the header will open twitter.com search page for that #hashtag. You may also choose to enable “safe mode”, which will exclude Tweets with common profanity and those marked possibly sensitive from appearing on your website.

Creating an Embeddable Timeline

To create a timeline you must be signed in to twitter.com and visit the widgets section of your settings page. From this page you can see a list of the timelines you've configured and create new timelines.

Click the “Create new” button to build a new timeline for your website, choose the type, and complete the fields in the form; most fields are optional. The configuration is stored on our server, so once you've saved the timeline a small piece of JavaScript is generated to paste into your page, which will load the timeline.

Here's an example embed code:

  1. <a class="twitter-timeline" href="https://twitter.com/twitterapi" data-widget-id="YOUR-WIDGET-ID-HERE">Tweets by @twitterapi</a>
  2. <script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src="//platform.twitter.com/widgets.js";fjs.parentNode.insertBefore(js,fjs);}}(document,"script","twitter-wjs");</script>

If you're already including our 'widgets.js' JavaScript in your page to show embedded Tweets or Twitter buttons, you don't need to include this script again; it updates automatically to support new features.

Customization Options

Embedded timelines are available in light and dark themes for customization. The light theme is for pages that use a white or light colored background and follows the twitter.com aesthetic, while the dark theme is for pages that use a black or dark color background and looks more like Tweetdeck.

As with your twitter.com profile, you may choose a custom link color for your embedded timelines so that the content matches the links of your website and feels integrated into the color palette of your site.

For sites where the theme and link color do not provide enough customization to make the Tweets feel like they're a part of the page, we offer a set of additional client side customization features. These settings allow you to control the background color, borders, header, and footer of the timeline, and are detailed in the "Client Side Options" section below.

Dimensions

Embedded timelines are flexible and adaptive, functioning at a variety of dimensions ranging from wide to narrow, and short to tall. The default dimensions for a timeline are 520×600px, which can be overridden to fit the dimension requirements of your page. Setting a width is not required, and by default the widget will shrink to the width of its parent element in the page. For example, if you paste your embed code in a div that is 300px wide, the timeline itself will be 300px wide. You can set the dimensions explicitly by using the width and height HTML attributes:

<a class="twitter-timeline" width="300" height="500" href="https://twitter.com/twitterapi" data-widget-id="YOUR-WIDGET-ID-HERE">Tweets by @twitterapi</a>

The minimum width of a timeline is 180px and the maximum is 520px. The minimum height is 200px.

Client Side Options

While all of the configuration settings are stored on the server, you may override specific options on the client side by customising the embed code. These settings are as follows:

  • Theme: Set by adding a data-theme="dark" attribute to the embed code.
  • Link color: Theme: Set by adding a data-link-color="#cc0000" attribute. Note that some icons in the widget will also appear this color.
  • Width: Set using the standard HTML width attribute on the embed code (units are pixels.)
  • Height: Set using the standard HTML height attribute on the embed code (units are pixels.)
  • Chrome: Control the widget layout and chrome by using the data-chrome="nofooter transparent" attribute on the embed code. Use a space-separated set of the following options:
    • noheader: Hides the timeline header. Please refer to the timeline display requirements when implementing your own header.
    • nofooter: Hides the timeline footer and Tweet box, if included.
    • noborders: Removes all borders within the widget (between Tweets, cards, around the widget.) See also: border-color.
    • noscrollbar: Crops and hides the main timeline scrollbar, if visible. Please consider that hiding standard user interface components can affect the accessibility of your website.
    • transparent: Removes the background color.
  • Border color: Change the border color used by the widget. Takes an #abc123 hex format color e.g. data-border-color="#cc0000"
  • Language: The widget language is detected from the page, based on the HTML lang attribute of your content. You can also set the HTML lang attribute on the embed code itself.
  • Tweet limit: To fix the size of a timeline to a preset number of Tweets, use the data-tweet-limit="5" attribute with any value between 1 and 20 Tweets. The timeline will render the specified number of Tweets from the timeline, expanding the height of the widget to display all Tweets without scrolling. Since the widget is of a fixed size, it will not poll for updates when using this option.
  • Web Intent Related Users: As per the Tweet and follow buttons, you may provide a comma-separated list of user screen names as suggested followers to a user after they reply, Retweet, or favorite a Tweet in the timeline. Use a data-related="benward,endform" attribute on the embed code.
  • ARIA politeness. ARIA is an accessibility system that aids people using assistive technology interacting with dynamic web content. Read more about ARIA on W3C's website. By default, the embedded timeline uses the least obtrusive setting: aria-polite="polite". If you're using an embedded timeline as a primary source of content on your page, you may wish to override this to the assertive setting, using data-aria-polite="assertive".

When these are set in the embed code directly, they'll override the server side settings.

<a class="twitter-timeline" href="https://twitter.com/twitterapi" data-widget-id="YOUR-WIDGET-ID-HERE" data-theme="dark" data-link-color="#cc0000"  data-related="twitterapi,twitter" data-aria-polite="assertive" width="300" height="500" lang="EN">Tweets by @twitterapi</a>

Here's another example that alters the default widget chrome settings:

<a class="twitter-timeline" href="https://twitter.com/twitterapi" data-widget-id="YOUR-WIDGET-ID-HERE" data-chrome="nofooter noborders transparent">Tweets by @twitterapi</a>

Finally, an example that renders a static block of three tweets:

<a class="twitter-timeline" href="https://twitter.com/twitterapi" data-widget-id="YOUR-WIDGET-ID-HERE" data-chrome="nofooter" data-tweet-limit="3">Tweets by @twitterapi</a>

Timeline Selection

Sites and applications can use an embedded timeline configuration for multiple timeline sources. For example, a social network can generate a timeline for any of its members on their profile page, or a blog can include the recent Tweets from any of its authors after their posts.

You should configure a timeline widget from your settings page as normal. Then, use the following attributes to override the source timeline:

  • Users: Add the data-screen-name or data-user-id attribute for the user whose timeline you want to display. You can also specify data-show-replies="true" to toggle the ‘Show Replies’ option on a per-timeline basis.
  • Custom Timelines: Add a data-custom-timeline-id attribute for the custom timeline you want to render. Use only the integer portion of the custom timeline ID.
  • Favorites: Similarly to user timelines, add a data-favorites-screen-name or data-favorites-user-id attribute for the favorites timeline you want to render.
  • Lists: To render a list, you must specify the list owner—data-list-owner-screen-name or data-list-owner-id—and a list identifier, data-list-id or data-list-slug.

For the most robust user experience, you should also ensure that you set the href of the embed code to the corresponding, appropriate location in case the widget is temporarily unavailable.

Please note that at the present time, it is not possible to override search queries.

Example syntax for overriding a user timeline, to show an author's recent Tweets after an article:

<a class="twitter-timeline" href="https://twitter.com/tatiana"
   data-widget-id="YOUR-WIDGET-ID-HERE"
   data-screen-name="tatiana" data-show-replies="false"
   data-tweet-limit="5">Tweets by @tatiana</a>

Example to display a specific list timeline:

<a class="twitter-timeline" href="https://twitter.com/brianellin/platform-products"
   data-widget-id="YOUR-WIDGET-ID-HERE"
   data-list-owner-screen-name="brianellin" data-list-slug="platform-products">
   Tweets from the Twitter platform team.
</a>

Example to display a specific custom timeline:

<div class="twitter-timeline" 
     data-widget-id="YOUR-WIDGET-ID-HERE"
     data-custom-timeline-id="393773266801659904">
     Music Superstars
</div>

Mobile

Like other components of the Twitter for Websites suite, embeddable timelines offer excellent mobile browser support:

  • Works on major smartphone browsers.
  • Interface is adaptive for touch (e.g. actions will always be visible, and spacing adjusted.)
  • Graphics optimized for Retina and other high-density displays.
  • Uses web intents for interaction, which also are designed adaptively for mobile.
  • Mobile device support is automatic, using the same embed code.

Restrictions and Rate Limiting

Embedded timelines are not subject to traditional Twitter API rate limits, and are designed to scale with your site as your traffic and audience grows. By using them, you are agreeing to Twitter's Developer Rules of the Road.