Add Twitter to your blog (step-by-step)

Due to recent changes in the twitter API auth policy, the current version of twitter.js does not work. I am actively working on a solution, but can’t say much more than that right now. If I do find a decent solution, you shouldn’t need to change anything as twitter.js will inherit the latest code automatically.

Hotlink from Google

<script src=""></script>

Download to self host

Download latest Twitter.js

Following on from how to add Twitter without hanging your blog, as requested, here is a step-by-step guide to adding Twitter to your blog without it hanging your web site.

Below is a working example of loading twitters after the page has completed, thus preventing the whole page from locking up (notice that the spinner will continue until the twitters are loaded) – based on my tweets from myself:

Please wait while my tweets load

Using my twitter.js script.


The function tags the following parameters:

  • CSS id of target element
  • Settings object (details below)

Settings object:

  • id: your screen name on Twitter, for example mine is “rem“. This can also be a list (in the format of user/list-name, ie. rem/conferences) or a hash tag.
  • count: number of twitters you want, defaults to 1.
  • clearContents: if you have content in the container you may want to clear it. Defaults to true.
  • enableLinks: true/false – scans the tweet for a link and makes it clickable, includes @replies and #hashtags, by default is true.
  • ignoreReplies: true/false – skips over tweets starting with @. If requesting 1 tweet, and this flag is set, behind the scenes it will request 2 in case the first starts with @ – but if the 2 most recent are replies, nothing will be shown.
  • currently disabled withFriends: true/false – whether to include friends tweets. Defaults to false.
  • template: the HTML template to use within each li element. See below for template variables.
  • prefix: if not using a template, you can use this. If you want to prefix each twitter, add here, e.g. ‘Remy said’. Note that you can use template variables in this field.
  • timeout: Number of milliseconds before triggering onTimeout. If onTimeout is set, timeout defaults to 10 seconds.
  • onTimeout: Function to call when timeout is reached. Context is set to HTML element tweets were going to be inserted into.
  • onTimeoutCancel: true/false – if not set, the timeout can trigger, but then the Twitter script could complete and override the cancel. To avoid this, set onTimeoutCancel = true. Defaults to false.
  • newwindow: true/false – if set to true, all links in tweets (and otherwise) will open in a new window. Defaults to false.
  • callback – Function to call when the twitter render is completed. Doesn’t fire if the script times out.

For example:

getTwitters('tweet', { 
  id: 'rem', 
  count: 1, 
  enableLinks: true, 
  ignoreReplies: true, 
  clearContents: true,
  template: '"%text%" <a href="">%time%</a>'

Template variables

All variables should be wrapped in % symbols (see the above example).

  • text – the actual status message
  • id_str – id of status message (note that id was used before, but for the ids to be correct, you need to use id_str)
  • source
  • time – relative ‘friendly’ time
  • created_at – raw time
  • user_name – real name
  • user_screen_name – username
  • user_id_str
  • user_profile_image_url – avatar
  • user_url – home page
  • user_location
  • user_description

Container HTML

You need to insert a holder element for the twitters to go in to. In the example above, I’ve included some ‘waiting to load’ content – but you don’t have to.

Here’s what I did:

<div id="tweet">
 <p>Please wait while my tweets load <img src="/images/indicator.gif" /></p>
 <p><a href="">If you can't wait - check out what I've been twittering</a></p>

Here are some more progress indicators.

If you include contents inside the holder div, then you’ll need to set the ‘clearContents’ flag.

Add the script

You can directly from the Google code repository (as seen in the example below).

Add the following code within the head or (best at the bottom of the) body tag:

<script type="text/javascript" charset="utf-8">
getTwitters('tweet', { 
  id: 'rem', 
  count: 1, 
  enableLinks: true, 
  ignoreReplies: true, 
  clearContents: true,
  template: '"%text%" <a href="">%time%</a>'

(this example will generate my twitter status in quotes on a single line with the ‘ago’ linkable back to the original twitter post)

Note that the getTwitters function will execute after the page has been loaded by your browser. It will fire once the DOM is loaded but before images are loaded.


If you don’t use a template, then the HTML is generated for you.

Each block of text is contained with in a span and includes it’s own class, e.g. the HTML generated would look like this:

<div id="tweet">
      <span class="twitterPrefix">Remy said: </span>
      <span class="twitterStatus">I just had a bizarre spaces moment - moving my cursor to the bottom of the screen switched space - annoying if it hadn't just gone away.</span>
      <span class="twitterTime">20 minutes ago</span>
      <span class="twitterPrefix">Remy said: </span>
      <span class="twitterStatus">Great quote - Michael J Fox: "my happiness grows in direct proportion to my acceptance, and in inverse proportion to my expectations."</span>
      <span class="twitterTime">7 days ago</span>

So each block of content is targetable using CSS to style the way you wish.

Comments, feedback or suggestions will be more thank welcome.

494 Responses to “Add Twitter to your blog (step-by-step)”

  1. Mate, That was Fantastic. Now one question, How do I make it so that it refreshes it self, so I dont have to refresh the whole site, to ge the latest Tweet.

    Thank you.

  2. Is there any way to use this script without specifying an id of an element? Eg. by inserting it in an nth section/article in the document? I’m trying to create a stylesheet without id-s and classes, and I’m having trouble decyphering your code to use something like document.getElementsByTagName.

  3. Great!
    And also easy explantation, even for a noob like me. Works well on my blog.

  4. Rem: great twitter code, really nice work. Thank you for your hard work you’ve put into it.

    I like Faraz think it would be a nice option to have some type of ‘time to refresh function date.getSeconds() = time_update’. If it wouldn’t require too much extra time and work .

    P.S. Your “Hotlink from Google” is missing ‘ type=”text/javascript”> ‘, someone unfamiliar with the syntax may get an error.

  5. @The_Anarchist – re: the “missing type attrib” – only the closing > was missing – the type attribute isn’t required as it’s consistently defaults to JavaScript in all browsers going further back than IE4 – so I’ve started stripping it.

  6. Is it possible to not publish RTs?

  7. Hello Remy,

    very nice and easy to use. One question, though: Is it possible to use the fetched tweets within the JS as a variable to reprocess the content using JS?


  8. Hi there, I am hoping you can help me with something. The “created_at” time is incorrect… I verified that my time settings on twitter are correct, I tried the google url and downloaded it to my server to self host as well with the same issue. I also verified that my time settings are correct in WordPress, and made sure that my server date and time are correct. I am at a loss.

    Do you have any suggestions.

  9. I’m having a heck of a time getting Cufon text to style the tweets! I saw someone else pretty far up the comment chain was having the same problem, but I didn’t see if there was a solution. Is it even possible?

  10. Any ideas, Remy?

  11. hello, thanks for a great script :)

    is it possible to display re-tweets? has anyone figured out how to do this??

    many thanks

  12. Is there a way in the template section of just getting the date in a format like
    27 Jun 11 or Mon 27 Jun without the time, or even better is there a way of getting day , month, year as separate variables?

  13. For everyone trying to display retweets:

    search for ‘var url’ and replace the twitter url line with:

    var url = '' + (options.withFriends ? 'friends_timeline' : 'user_timeline') + '.json?screen_name=' + id + '&callback=twitterCallback' + guid + '&count=20&include_rts=true&cb=' + Math.random();

  14. Hi Remy, great script, but as others have asked

    a) is it possible to get it too refresh automatically ?
    b) Could you expand the date formatting so we can format for ourselves, for example, allow us to add Time Zone, 24 hour etc.

    Many thanks


  15. Thanks a lot ! Very nice script !
    is it possible to change the date format ? I’m using for now the googlecode source.
    I would use it on a french website four youngs, and I’d avoid the ‘Created at’ sentence, or replace it with french terms, or at least place a readable date format.
    Thanks again.

  16. Remi, thank you! I’ve been using this script for years now, but adding the spans inside the javascript template makes it invalidate using XHTML transitional:

    template: '%user_name% tweeted:

    Can you offer another way to create styllable classes that validates?

  17. NewWindow parameter is not working

    getTwitters(‘tweets’, {
    id: ‘jbrandjeans’,
    count: 4,
    enableLinks: true,
    ignoreReplies: true,
    clearContents: true,
    newwindow: true,
    template: ‘%text% %time%

  18. How can I make the Twitters appear by word search? For example, my id is set to xrdnet, which displays tweets from!/xrdnet.

    What if I want tweets from xrdnet, but only those tweets that contain the word “Japan”? Or any other specific word?

  19. Remy-san,

    Great work! The tweets/retweets usually disappear after a couple of days because does not store them longer. However, I have seen some sites like this where it keeps the tweets using scripts like yours. What can I do to prevent these tweets from disappearing?

    Thank you,

  20. Found the answer on another site. For Cufon text fonts to show you have to add a callback

    callback: function() {

  21. This is great stuff.
    I’m just wondering how do you go about dealing with Twitter’s API limit request?

  22. Hey Remy. Just wondering if you could help me figure out why the twitter code I put in loads in every browser perfectly, except for IE8, which loads it fine on every page but the homepage.

    I appreciate the help!



  23. Alright, well I got it to work. Instead of calling the hosted version from Google (

    I downloaded the latest 1.13.1 release, uploaded and called my own hosted version of the full ‘twitter.js’ (

    Was anyone else having IE8 problems?

  24. It is possible setting multiple twitter accounts? How? If is not, you could take this as a suggestion :)

  25. Any idea how i can use Jquery cycle plugin with this?

    i would like to cycle 4 of my latest tweets – but the UL is wrapped in a DIV – which the UL could be the wrapper.

    has anyone tried this before? excellent stuff with this twitter.js file.. its really easy to use and style…

  26. I’m working to adapt this for use with DNN. I’ll let you know if it’s successful! :)

  27. WoW that would be excellent – looking forward to see what you come up with…

  28. Hi Remy, great script, impressive JS programming in the details.

    I’ve tried to modify it to have twitter search #hashtags instead of @ids. If I set the API call URL to…, twitter returns a different dataset, starting with twitterCallback1({“results”:[….

    How would your JS need to be modified to get rid of the results section, and process the search query result in lieu of the user status?

    Thanks in advance, Ulf

  29. It appears that anchor tag links within the tweet %text% are being returned as null when using the template parameter. Any insight into this? Thanks!

  30. This is such a great piece of code.

    How does this deal with the Twitter’s API call limit?
    It won’t load on any PCs on our office network – I’m assuming our server has made too many calls. How do we get around that?

  31. Hi Remy,
    thanks for this amazing library.
    It seems the “includeRT” parameter doesn’t work cause it always sends include_rts=false to get the timeline.
    I had to force include_rts=true in twitterlib.js to get RT on my website but I guess there’s a much proper way to do it.
    Anyway, thanks again.

  32. Calling the script from Google code has stopped working for me on various browsers. Fails on different servers, and on local pages as well (calling other scripts from Google code, eg jQuery works fine).

    I’m using the call as above, and I didn’t change anything on the sites that are affected. Tested on 3 different computers, didn’t change any settings. According to the Activity window (Safari), the script does load, but nothing is shown – replacing it with a local copy of the script solves it (only tested on local page so far).

    Google Chrome and Mobile Safari don’t seem to have that problem. Fails everywhere (Safari/Mac, Firefox/Mac, Opera/Mac, ie/Win, Firefox/Win) except in Chrome and Mobile Safari.

    Anybody having the same problem? Any ideas where/what to check?


  33. Yes, I think there is currently an issue with the ignoreReplies option when it is set to true. Try using the following link, which is an earlier version of the code that doesn’t have this issue, or setting the ignoreReplies option to false.


  34. I am also having the problem… stopped working on explorer and firefox, but works on my iphone.

    Also still works on Dev but not on production?

  35. Yep works in safari but not firefox? So strange as I have used this loads of times before with no problems!

    Edit: Reverted back to 1.13.1.min.js and working again, must be a problem with 2.0 :S

  36. Love the script Remy, but right now even your demo version above is producing no tweets in IE9. Works fine for me in everything else and judging from the activity on Google’s hosted script issue pages it isn’t confined to twitter.js.

    Any ideas what is causing this or when we are ikely to see a solution? – I don’t want to switch scripts as yours normally works brilliantly and allows me style tweets just as I want.



    P.S. Using twitter.min.js latest Google-hosted version on IE9/Mac

  37. For those seeing issues with IE9 – this turns out to be a problem that Twitter are aware of and trying to fix – so hold on tight and check their status page here (note – this will affect all twitter badge apps) – in here:

  38. Stopped working again, across all of my sites, in all browsers (this time including Chrome and Mobile Safari). With or without @replies.

    I’m testing locally and on one of the servers I use: the hotlink from Google doesn’t work, the script from your download link doesn’t work, but the script you’re using on this page here works fine: is only reporting performance issues for ‘statuses/home_timeline (OAuth 1.0a)’

    Any pointers?


  39. Hi there Remy,

    Love the script but I want to be able to host all the files on our server, so that I can ensure we are not reliant on any other includes.

    I have downloaded the zip file, but I notice that the twitter.min.js includes a file from

    can I ask why this is, and how I can replace this.

    Many thanks


  40. @Mark – twitterlib is the upgraded script, and I switched twitter.js over as a wrapper to twitterlib some months ago. It would be probably easier for you to use twitterlib.js directly and you have more control – plus there’s some decent documentation and samples: (code and docs), API demos:

  41. Hi Remy,

    Thanks for the very quick reply, will have a look now.

    Many thanks


  42. I’ve get error when using your script:
    GET 403 (Forbidden)
    Hotlinking to Github is bad idea ;)
    I download this script, upload it to My site and changed adress in twitter.min.js, and it works now for Me.

  43. @Grawl – good spot, though I changed this some time ago (and the google hosted version doesn’t point to the raw github url for some time). It points to a ‘pages’ hosted version. Basically twitter.js is a shim to twitterlib now which has more functionality.

  44. It points to a ‘pages’ hosted version. Basically twitter.js is a shim to twitterlib now which has more functionality.