Scripting: Factory Functions

If you’re integrating your site with Twitter using Twitter for Websites and Web Intents, you can dynamically generate widgets using JavaScript functions.

Twitter for Websites products—Tweet buttons, Follow buttons, embedded Tweets and timelines—are all loaded using a JavaScript utility named widgets-js. When adding a Twitter widget to your page, this JavaScript file is included in the HTML embed code, or you can directly include https://platform.twitter.com/widgets.js in your page. (See the Twitter for Websites set-up documentation for a recommended code snippet.)

By default, widgets-js will find mark-up in a page and convert basic, functional mark-up into rich interactive widgets. In addition, there are a number of functions of widgets-js that allow you to work with Twitter content dynamically:

Creating widgets at runtime with factory functions

Widgets can be generated at runtime, without requiring an HTML embed code. A set of factory functions can generate any widget type:

Buttons

createShareButton, createFollowButton, createHashtagButton, and createMentionButton take similar arguments.

Primary Argument

 

The first argument is required, and is unique to the button type. Provide a string representing one of:

  • url: The URL to be shared.
  • screen_name: The screen_name of a user to be followed, or mentioned.
  • hashtag: Hashtag to be Tweeted and displayed on the button.

Additional Arguments:

 

  • target: Required. The element in which to render the widget.
  • options: Optional. An object hash of additional options to configure the widget.

Note that widgets usually render as iframe elements. When an iframe is moved within the DOM the browser will reload its content. For buttons this can waste bandwidth, while for Tweets and timelines this will cause dynamically injected content to be lost. Use the target argument to render widgets into their final location in a page. If you need to delay the display of a widget, use CSS to position the widget off-screen until needed.

Every create function returns a Promise. You can execute code after a widget has been created by passing a callback to:

      twttr.widgets.createFoo()
.then(function (element) {
  console.log("Widget created.")
 });

When fulfilled, the promise will pass a reference to a newly created widget element to the chained callback.

Examples:

Create a share button for a URL:

      twttr.widgets.createShareButton(
  '/',
  document.getElementById('new-button'),
  {
    count: 'none',
    text: 'Sharing a URL using the Tweet Button'
  }).then(function (el) {
    console.log("Button created.")
  });

Create a Follow button for a user:

      twttr.widgets.createFollowButton(
  'endform',
  document.getElementById('new-button'),
  {
    size: 'large'
  }).then(function (el) {
    console.log("Follow button created.")
  });

Options

Additional configuration and options can be passed to the factory functions, as in the above examples.

Additional configuration for all widgets

Option Values Default Notes
lang An ISO 639-1 language code. en The language in which to render a widget, if supported (see the Translation Center.)
dnt true, false false When set to true, the embed and its embedded page on your site are not used for purposes that include personalized suggestions and personalized ads
related Any comma-separated list of valid Twitter screen names. Undefined A list of Twitter screen names to be suggested for following after a Tweet or Tweet action is posted.
via Any valid Twitter screen name. Undefined A Twitter user mentioned in the default Tweet text as via@user where appropriate.

Additional configuration options for button widgets

Option Values Default Notes
align left, right locale dependent (left or right, depending on the text direction of the language.) The alignment of the button within an iframe; use this to ensure flush layout when aligning buttons
size medium, large medium  

Tweet button additional options

Option Values Default Notes
text Any string Undefined The default, highlighted text a user sees in the Tweet web intent
hashtags A comma-separated list of hashtags. Undefined A list of hashtags to be appended to default Tweet text where appropriate.

Tweets

createTweet takes the ID for a Tweet, and then the same additional arguments as for buttons.

Arguments

 

  • tweetId: The ID of a Tweet to be rendered. (This should be provided as a String, since Twitter IDs are generated from 64-bit integers, and JavaScript integers are limited to 53 bits.)
  • target: Required. The element in which to render the widget.
  • options: Optional. A hash of additional options to configure the widget.

Examples:

 

Create an embedded Tweet for a Tweet from the US Department of Interior:

      twttr.widgets.createTweet(
  '511181794914627584',
  document.getElementById('first-tweet'),
  {
    align: 'left'
  })
  .then(function (el) {
    console.log("Tweet displayed.")
  });

Options

Option Values Default Notes
conversation none, all all Tweets in response to another Tweet will display a compact version of the previous Tweet by default. Use none to hide the parent Tweet in the conversation
cards hidden, visible visible Hide photos, videos, and link previews powered by Cards.
width Positive integer auto, derived from container size Set the maximum width of the embedded Tweet
align left, right, center Undefined Float the embedded Tweet to the left or right so that text wraps around it, or align center so it floats in the middle of a paragraph
theme dark, light light Toggle the default color scheme of the embedded Tweet

Timelines

createTimeline takes the data source definition for a timeline. Additional arguments are consistent with embedded Tweets.

Arguments

 

  • data source: Required The data source definition object for the content to be displayed in the widget. May be a widget ID string for a legacy widget
  • target: Required. The element in which to render the widget.
  • options: Optional. A hash of additional options to configure the widget.

Examples:

Create a timeline widget:

      twttr.widgets.createTimeline(
  {
    sourceType: 'profile',
    screenName: 'twitterdev'
  },
  document.getElementById('timeline'),
  {
    width: '450',
    height: '700',
    related: 'twitterdev,twitterapi'
  }).then(function (el) {
    console.log('Embedded a timeline.')
  });

Data Source

The data source definition describes what content will hydrate the embedded timeline. There are several types of data sources: profile; list; URL; widget configuration.

Profile

 

To power an embedded timeline with Tweets from an individual user use a profile data source. To do so, set sourceType to profile and set one of screenName or userId

Options for profile data source:

Option Values
sourceType profile
screenName Valid Twitter username
userId Valid Twitter user ID 
      twttr.widgets.createTimeline(
  {
    sourceType: 'profile',
    screenName: 'twitterdev'
  },
  document.getElementById('container')
);
List

 

To power an embedded timeline with a Twitter list use a list data source. Set a sourceType to list and set both ownerScreenName and slug or set an id.

Option Values Notes
sourceType list  
ownerScreenName Valid Twitter username Used with slug
slug The string identifier for a list Used with ownerScreenName
id Valid Twitter list ID

 
      twttr.widgets.createTimeline(
  {
    sourceType: 'list',
    ownerScreenName: 'twitter',
    slug: 'official-twitter-accts'
  },
  document.getElementById('container')
);
URL

To power an embedded timeline with Twitter content represented by a URL use a url data source. Supported content includes profiles and lists.

Option Values
sourceType url
url Absolute URL of a Twitter profile or list  
      twttr.widgets.createTimeline(
  {
    sourceType: 'url',
    url: 'https://twitter.com/twitterdev'
  },
  document.getElementById('container')
);

Options

All the parameters described above for all widgets and for embedded Tweets apply also to embedded timelines.

Option Values Default Notes
chrome noheader, nofooter, noborders, transparent, noscrollbar Undefined Toggle the display of design elements in the widget. This parameter is a space-separated list of values
height Positive integer 600 Set a fixed height of the embedded widget
tweetLimit Range: 1-20 Undefined Render a timeline statically, displaying only n number of Tweets.
borderColor Hexadecimal color Varies by theme Adjust the color of borders inside the widget.
ariaPolite polite, assertive, rude polite Apply the specified aria-polite behavior to the rendered timeline. New Tweets may be added to the top of a timeline, affecting screen readers

For more information on the options for customizing embedded Timelines refer to Embedded Timelines.

These functions make it possible to integrate Twitter user’s content into your site dynamically in a JavaScript application, and integrate user interactions into your own application experience.

Please ask questions and share your code and examples in the developer forum. You may also refer to the main Twitter for Websites documentation.