Add to home screen

Add To Homescreen (ATH) is a javascript widget that opens an overlaying message inviting the user to add the web site/application to the home screen. This was born mainly to support web-app-capable applications but extended to a more general purpose use case.

Support Development

Add To Homescreen is a free, open source javascript software. It is released under the MIT License which basically grants you complete freedom in usage for open source and commercial applications.

That being said the only way for me to subtract hours from my day work and keep implementing this script is through donations. If you find this widget useful and wish to support future development, please consider a donation.


The script opens an always-on-top message inviting the user to add the application to the home screen. This is currently supported on iOS and Mobile Chrome. While other devices have the ability to bookmark any website to the home screen, only iOS and Mobile Chrome have a straightforward way to do it. ATH would technically also work on Windows Phone (which has the equivalent Pin to Start option), but I’m not currently able to test it on that device. WinPhone support might be added in a future release if there will be enough interest.

ATH by default looks something like this


But appearance is customizable with plain old CSS.

The script is compatible with iOS 6+ and Chrome 31+. It would be possible to add iOS5 (and older) support, but considering the iOS7 penetration I decided to support the latest two releases only. If there’s really interest in older versions I might reintroduce <iOS5 support or you could use the previous version of ATH (which supports iOS3 and up).


The message changed in v3 so unfortunately all the languages supported in v2 are not available anymore. If you wish to help please send more translations!

Basic Usage

v3 API changed drastically (sorry about that) and it’s not a drop in replacement for v2. The good news is that v3 is aware of user sessions saved on previous ATH versions, so if the users have already seen the message, it won’t be displayed again.

The easiest way to use ATH is to link the script into your document HEAD and call the addToHomescreen() function as soon as possible. Eg:

<title>Add To Home</title>
<link rel="stylesheet" type="text/css" href="../../style/addtohomescreen.css">
<script src="../../src/addtohomescreen.js"></script>

That’s all you need. ATH automatically hooks to the onload event, checks device compatibility, detects if the app is already in full screen mode and eventually pops up the message.

It is not strictly needed to place the script in the document HEAD (you can also place it at the end of your BODY), but ATH makes a series of checks that are better done sooner than later.


ATH accepts one option parameter to customize the script behavior.

To change the start up delay for example you could use the startDelay option.

   startDelay: 5

This would delay 5 seconds before showing the message.

Below the most common options.

  • modal: prevents further actions on the website until the message is closed.
  • mandatory: the website is not accessible until the user adds the application to the homescreen. This is useful mainly for web-app-capable applications that need full screen viewing to be accessed (eg: games).
  • skipFirstVisit: setting this to true prevents the message to appear the first time the user visits your website. It is highly recommended to enable this option!
  • startDelay: seconds to wait from page load before showing the message. Default: 1.
  • lifespan: seconds to wait before automatically close the message. Default: 15 (set to 0 to disable automatic removal).
  • displayPace: minutes before the message is shown again. By default it’s set to 1440, meaning that we will be showing the message only once per day.
  • maxDisplayCount: absolute maxium number of times the call out will be shown. (0 = no limit).
  • icon: display the touch icon in the pop up message. Default: true
  • message: you can provide your custom message if you don’t like the default.
  • onShow: custom function executed when the message is shown.
  • onAdd: custom function executed when the application is added to the homescreen. Please note that this is a guesstimate (see below).
  • detectHomescreen: ATH tries to detect the homescreen. Supported values are: false, true (=’hash’), ‘hash’, ‘queryString’, ‘smartURL’ (see below).
  • autostart: the message is not shown automatically and you have to trigger it programmatically.

Detect the homescreen

There’s no native event we could hook to to know when a user actually adds the page to the homescreen. That’s also the reason why this script has become so complicated despite the apparent simple task it has to accomplish.

ATH development started when Apple introduced the apple-mobile-web-app-capable meta tag and stand alone mode with it. When the webapp is in stand alone mode the window.navigator.standalone property is set to true and that’s the only 100% safe way to know if the app has been added to the homescreen… With some caveats (of course).

// set a web app capable website
<meta name="apple-mobile-web-app-capable" content="yes">
<meta name="mobile-web-app-capable" content="yes">

Standalone mode is meant for web applications, not “standard” web sites. The webapp has to be designed with standalone mode in mind, for example links inside your fullscreen app will open in a new browser window hence your app navigation has to be handled with JS.

Also, as of this writing Chrome –despite support for mobile-web-app-capable— doesn’t fill the window.navigator.standalone property, making it an unreliable way to detect if the app has been added.

So, how can we detect if the app has been actually added to the home screen? ATH tries its best to help you in this hard task and the followings are your options.

  • Show the callout only once per user. This is the best, safest and most polite solution of all. Set the maxDisplayCount to 1 and the user will be presented with the nasty callout only one time, smartly circumventing the problem.
  • Build a standalone application. When possible try to use apple-mobile-web-app-capable.
  • Add a special token in the URL and have the user bookmark the tokenized address. ATH supports hash, query string or smart url tokens. Continue reading for details.

I strongly suggest to go with the first option and show the callout only once. That’s the safest solution, but if you want to be more aggressive you can take the “token” route.

First of all you have to choose where to place the token. ATH offers three options:

  • hash:
  • query string:
  • smart url:

As soon as the page is loaded ATH adds the token to the page URL (no worries, no reload will happen as we use history.replaceState). If the user adds the page to the homescreen the actual URL that will be saved contains the token. If the page already contains the token before ATH could add it, it means that (most likely) the page has been added to the homescreen.

Bear in mind that this is a guesstimate, there are some exceptions but the good news is that it should be pretty rare to have false positive, ie: it should never happen to see the popup after the app has been added. Instead it may happen to have ATH think that the app has been added even if it hasn’t.

Be careful when using the detectHomescreen option since it may interfere with your application especially if you already use #hash or history.replaceState for your navigation.

Optimal configuration

Do not annoy your users with frequent callouts the suggested setup is to show the message only once, the second time the user visits your website.

   skipFirstVisit: true,
   maxDisplayCount: 1

The above config skips the first time the user comes to your site, so she has time to look around freely. The next time she will be greeted by the cheerful balloon and from that moment on she won’t be bothered again.

Debug mode

ATH v3 also introduces debug mode. By setting debug: true some of the preliminary checks are skipped and the message is shown on desktop browsers and unsupported devices as well.

You also have the addToHomescreen.removeSession() function in your tool belt, which clears the current session. This is very useful when testing various options and the callout seems not to be willing to show up again. This is common because ATH is very conservative, to avoid showing the message by mistake it tries to show it the less as possible.

Open the pop up programmatically

Of course you can bypass the automatic triggering and open the call out programmatically. To do so you have to set the autostart: false option.

var addtohome = addToHomescreen({
   autostart: false

addToHomescreen() it’s a kind of singleton and returns the instance to the real AddToHomescreen class. From there you have access to the show() method. Note that no checks are performed to verify if the DOM is ready, if you show the message programmatically that’s up to you.

show() also supports one boolean option. If you pass true the callout is shown no matter what overriding most of the preliminary tests.

localStorage variable name

The user session is stored in a localStorage variable called org.cubiq.addtohome by default. localStorage is domain based, so if you have multiple applications on the same domain ATH can’t understand which one you actually added to the homescreen.

You can have multiple instances of ATH on the same domain by setting a different appID for each installation. Eg:

   appID: 'org.cubiq.myCoolApp'

IMPORTANT: once set do not change the appID! If you change the appID all users will see the callout again regardless if they already added the application to the home screen or not. Only exception is for standalone applications. They would keep working correctly anyway.


From iOS6 you have a handy meta tag called apple-mobile-web-app-title that holds the name that will be displayed on the homescreen, otherwise the page title will be used. Since the app name is limited to 11 characters you may want to take advantage of this feature.

799 thoughts on “Add to home screen”

  1. Very nice, Matteo. I tried it, but the close button gives an ‘A’ instead of an ‘x’. Any idea where to change this?
    Thank you.

    1. Same problem. There is a A instead of a x. I changed it to iso-8859-1 before and now change back it to utf-8, but same.

    2. I’m having the same problem. and im unsure what should be on line 115. could you help me out a little


    3. I had the same issue(I was actually using javascript files served by PHP, so it was likely an encoding issue), but I was able to avert the issue by simply replacing the x character with the unicode escape (u00D7).

  2. I’ve seen several sites using a script like this, and sometimes it gets activated when I’m viewing the page inside a third-party app (Twitter, Instapaper, etc.) So of course it’s pointing to a button that doesn’t exist. I wonder if there is a solution for that.

  3. Wow great very nice.

    The localization is great.

    Would be great if it would be possible to localize a whole webapp with a XML file. I found this:

    But i do not know how to implement it so that the language detection choose the right language.

    Maybe that would be something for our “webapp master”


  4. hurray for Matteo, as his cube continues to spin, can’t to see what iScroll4 brings

  5. I’m not much of a mobile developer, but from what I can see this effect looks money. I’ve also really enjoyed your blog. You should write about Web Dev more since you obviously have the touch.

  6. That’s awesome!!! Thank you very much. Do you guys know something like this for Android phones?

  7. This is a great and very helpful addition to a website’s general user interaction — there’s just one little thing: Is there any chance to detect whether the web app was started from the home screen to then prevent the message to show up?

    Because after a user saved the website to his home screen it might become a bit annoying to stil see the message at every visit.

    Many thanks for your great effort and any further development.

  8. I have this working fine on a couple of sites, but can’t seem to get it working with jQTouch – is this something you are aware of? Do I need to do anything differently? Many thanks.

    1. Bit more info…debugging tells me that all the required functions are called, even calls the start of the drop animation, just nothing being displayed. Seems jQTouch prevents the div from showing?? Not sure. Can anybody shed any light on this?

  9. Thanks for reply. I added:”999″;

    But no difference. I’ll check through for style conflicts as well – if I find anything I’ll let you know!

    1. No joy I’m afraid. Can’t see why it’s not displaying, zindex is set very high in css in any case, and no style conflicts from what I can see. Must be to do with jqtouch.js or a maybe a funny version of jquery.js ? Anyway, I’ll keep trying…

  10. Well, I got it working. With jQTouch, I couldn’t find a way to have the div append to the body as it was always rying to do so before the page load, due to the way jqt works.

    Anyway, I changed :




    And it works fine! So looks like a workaround for those wishing to use this with jQTouch.

    1. Where i have to change this string? in my jquery.js file? on my php document? can you post you entire code please? Help me :-))

  11. Hey, good solution. Just to report you that on ipad – atomic browser, works emulating iphone, but as ipad doesn’t work.

    Using safari no problems.


  12. Thanks alot. Anyway to have the bubble always appear in all browsers? ( easy to firebug and so on.. )

  13. This is a brilliant piece of code!
    I showed the results to my boss and he got seven kinds of excited and wants me to update the production code immediately.

  14. This is great. Added it to one of my projects!

    My first web app and it works great.

    Do you know why once I have added it to my homescreen it loads fine and I get the homepage, but when I click a link within my website it opens up in Safari?

    Do you know why it does this?

  15. On iPhone 4 it works great, but what happens to iPod Touch 4? 🙁 I’ve testeted it on both devices and only iPhone 4 shows it.

  16. Well, Maybe that’s because I’ve implemented it on a dashcode web application ready project and something is messing up the code or even I’ve messed it up myself, I’ll double check it.

    Thanks for the info.

  17. Actually for me it is not showing up on the iPod Touch 4, even if I access the Demo link from the device it doesn’t work at all. Would it be because I’ve got it jailbroken? I mean this script checks the iOS version to show the correct icon etc. doesn’t it?

    Any help is welcome.

    Thanks in advance.

  18. Here´s a Finnish translation (there´s lot´s of iOS web-app productions going on in Finland right now):

    Asenna tämä web-ohjelma työpöydällesi: Paina [ ] -kuvaketta ja valitse “Lisää kotivalikkoon”.

  19. Does anyone else using this on the iPhone have a problem with the latest version of the i-nigma barcode reader?

    They’ve started opening the links in their own micro-browser, and I get a big fat NSURLErrorDomain error – 999 alert box over the loaded page, and the javascript execution breaks so the add2home bubble is never shown.

    Been trying in vain to catch and suppress that error…

  20. THANK YOU ! Another nice UI & very useful script. Strangely, the css-inline icon for the home screen button (the share icon, for iOS >=4.2) does not show up in my app on the iphone ( It does not show up in the XCode iphone/pad simulator either for me. Just shows a blank space there.

    I know it must be something I am doing wrong (since your demo works) but I cannot figure out what it is – can someone see it ?

    1. Ah silly mistake on my side. Nothing to do with your code (css minifier was eating the base64)

  21. Does the script check if the website is already installed at the home screen? I ask, because the message is shown to me, even if I start the web app _from_ the home screen.

  22. Nice work! I’m a developer from Hong Kong and I’ve translated the Traditional Chinese and Simplified Chinese message for you:

    Traditional Chinese (likely to be zh_TW): 您可以將此應用程式安裝到您的 %device 上。請按 %icon 然後點選加入主畫面螢幕
    Simplified Chinese (likely to be zh_CN): 您可以将此应用程式安装到您的 %device 上。请按 %icon 然后点选添加至主屏幕

    Keep up the good work.

  23. Anyone know if there’s a way to get this to work with a wordpress/wptouch site? I’ve tried adding the code to the actual wordpress header, and the wptouch head file, but to no avail.

  24. Is there anyway to stop the message coming up after someone has already ‘installed the web app’?

  25. Yeah, still comes up on mine after having been added to homescreen, running iOS 4.3.3 on an iPhone 4 from a wordpress site with wptouch for the mobile interface.

  26. Thank you for this nice bit of code, I’m using it on a mobile site I’ve made for the iPhone.

    Very nice ! Wish I could do stuff like that 🙂

  27. Thanx, this is a really nice ‘function’ for my webapp. But I have 1 problem: My apple-touch-icon won’t show in advanced mode 🙁

  28. This seems nice, but it keeps asking the question over and over. How do you tell when to stop asking?

    1. expire:1440
      asks it once per day.
      only once per week.

      quote: “If you don’t want to show the message at each and every page load, you can set a timeframe in minutes. The message will be shown only one time inside that timeframe. Default: 0 (=always show).”

    1. Please update to the latest version. Also it is crucial that the JS file is served as UTF8. That should be default on recent webservers but you can force it by adding the following to your .htaccess:

      AddDefaultCharset utf-8
      AddCharset utf-8 .html .css .js .xml .json .rss

      If you don’t want to convert all your site to UTF8 you can serve just this script with the proper charset, like so:

      <Files “add2home.js”>
      AddDefaultCharset utf-8

      (Not tested but should work)

      If working with .htaccess is not possible, you may want to remove all languages but English from the script.

    2. I can’t. The download is .gz. I’d need a zip. The only version I can use is whatever you have setup for the demo. Can you update that to the latest version?

  29. Hi there,

    First of all, you make some cool stuff!
    What I noticed is that when you save the webpage on your homepage and you open it again, the website is an web app. How cool is that! But when you click on a link in that web app, you get redirected to Safari, so that’s kinda weird though.

  30. i used this in a webapp (duh…) and i really liked it,
    i’ve put you on my credits page (1 out of 3 pages) so you’ll get visitors from me as well =D

  31. Do you know of any way to get this working on Android? I’m working on a cross-platform web app… By the way, EXCELLENT SCRIPT! Thanks a lot man. It works flawlessly on my jQueryMobile site for iPhone and iPad (haven’t tested iPod, but I assume it’s the exact same). And it seems to be the only script of its kind as of 6/8/11.

  32. This script works excellent on a couple sites I’m working on.

    I’ve modified the code a bit so instead of launching the load event on window.load, I launch it on a button press (on a help button instead)

    Basically only had to comment out the event listeners and make the method public.

    But it only seems to run once. If I press the button again it goes through the motions but doesn’t seem to show anything.

    Any ideas?

    1. Nevermind.
      I realized the element was being removed in transitionEnd.
      As soon as I commented that out, I can make it appear as many times as I like.

    2. Hey Mark, could you post the lines you updated? I’m trying to do the same thing but I don’t know where exactly to tweak.

      Thanks in advance!

  33. Very cool script. Thank You

    Has anyone had an issue with ASP pages and the script? I tested the example and it works great under .html but when I change the extension to .asp I get the error. I changed this because most of my pages on my site are .asp

    Active Server Pages error ‘ASP 0138’
    Nested Script Block

    A script block cannot be placed inside another script block.

    1. The code still did not work. A friend of mine said he has it working on an ASP page. I will check it out and post the results if needed. Thanks!

  34. Great script!

    is ti possible to replace the word iPod with the word iTouch when it displays %device

  35. This is awesome! Had it working great, think it still is but I must have worn out my number of uses, definitely not more than 100, maybe 5-10? But iterations:100 is still set, is that not what I think it is or did I miss something (not a js person, really)? Thanks!

  36. @matteo

    i kinda figured thats where it would be… i dont know enough about javascript to do an if statement on the $device variable
    to display iTouch instead of iPod would you offer paid support to implement that change? if so how much?



  37. Great stuff!! It wasn’t working for me on a JQtouch webapp until I changed the following code in the add2home.js file:

    // take this existing line out:

    // and add the following with ‘home’
    // changed to whatever the first screen’s div ID is:

    I’m guessing there may be a better way to do this… but this worked for me so I thought it may help others

    thanks again Cubiq – GREAT work!!

    1. Thank you so much for this, Gaucho!! You really saved me. It wasn’t working and I was tearing my hair out until I found your post. Saved me so much time!!

    2. Hit the same issue with jQuery mobile (RC1). Made the hack as above and it works great.

  38. Ciao
    ho visto che sei italiano, una domanda: il tuo script mi sembra che non sia compatibile con jQuery Mobile, è vero o sbaglio io qualche cosa?

  39. how can I modify the code to only show the bubble message on the home page? I’ve tried adding

    if ($(‘body’).hasClass(‘front’)) {
    if (‘standalone’ in navigator && !navigator.standalone && (/iphone|ipod|ipad/gi).test(navigator.platform) && (/Safari/i).test(navigator.appVersion)) {
    var addToHomeConfig = {
    animationIn:’fade’, // Animation In
    animationOut:’fade’, // Animation Out
    lifespan:10000, // The popup lives 10 seconds
    expire:0, // The popup is shown only once every 2 minutes


    and also tried

    if (‘standalone’ in navigator && !navigator.standalone && (/iphone|ipod|ipad/gi).test(navigator.platform) && (/Safari/i).test(navigator.appVersion) && ($(‘body’).hasClass(‘front’)) {
    var addToHomeConfig = {
    animationIn:’fade’, // Animation In
    animationOut:’fade’, // Animation Out
    lifespan:10000, // The popup lives 10 seconds
    expire:0, // The popup is shown only once every 2 minutes


    Neither worked. I also tried to use a PHP code if statement for front page, but that stops the popup from displaying too.

    Thanks so much for any help!!

  40. Is there a way to tell whether or not they have already done this? I don’t want to annoy the crap out of users who have already added it.


    1. if they already added the app to the homescreen, they probably access it from the homescreen and if your app is in full screen mode the message is not shown.

  41. Thanks so much for all your time on this!

    Another issue I’m having is when the Safari Mobile address (header) bar gets hidden.

    It appears the calculation of the popup position gets calculated before the address bar is hidden. So, the address bar is visible for a moment, and then when it’s hidden the popup ends up 50 pixels or so above the Safari toolbar footer. It doesn’t seem to be a problem in the demo because the Safari address bar isn’t hidden.

    Any ideas on a way to fix this?

    Thanks for any help!

    Also, great blog post on iOS5 and fixed positioning…

      1. Thanks for the response Matteo.

        I have actually added a full screen splash div behind the popup in the js file and I’m using both as a startup/splash page for users in Mobile Safari. Anyway, I removed the fade and startDelay so that the splash screen starts right away. Both fade after 10 seconds, or when the close button is clicked.

        In order to get the popup to display at bottom of screen after Safari address bar is hidden, I have also tried to use the bottom offset to push the popup down with a negative value, but a few times the popup ended up below the Safari footer.

        Thanks again for any help.

  42. Have you tested this in conjunction with your iScroll script? I seem to be doing everything right (files load properly, and addToHomeClose is available), but I can’t seem to get it to show up. I’ve tried doing what Gaucho recommends above (replacing document.body.appendChild(div) with document.all.main.appendChild(div)) but it doesn’t seem to help. (I’m using iScroll on #main, with an inner element of #event-list).

    Any ideas?

  43. I am not able to get the touchicon beside the message in the bubble. I have done the following:

    touchicon: true;

    I have added the following lines in my head tag:

    link rel=”apple-touch-icon” href=”../apple-touch-icon.png” type=”image/png”/
    link rel=”apple-touch-icon-precomposed” href=”../apple-touch-icon-precomposed.png”/
    link rel=”apple-touch-icon” sizes=”72×72″ href=”../apple-touch-icon-72×72.png” /
    link rel=”apple-touch-icon” sizes=”114×114″ href=”../apple-touch-icon-114×114.png” /

    but still I am not able to get the touchicon image in the bubble.

    Any ideas please??

    Thanks a lot in advance. 🙂

      1. I am working in mobile. I need to create a user control and only then it will work. I didnt know this before and though there was a mistake in script. My mistake. Works now perfectly.

        Great script though!

        One more thing. This bubble shows up even after user adds to home screen. Can the script be updated in such a way that, once user adds to home screen, the bubble should not show up.

        I dont know how feasible it is. But just wanted to know.


      2. Maybe visitor still uses Safari to see the bubble. If in Safari we can not detect if already added to home screen, the only solution will be cookie. Correct me if I am wrong.

    1. Report means… do you want a screencast or ..?

      What do you want the report to contain?

      Sorry for such dumb question, but I m new to development. 🙂


      1. Its I tested it using Iphone 3G. I made a change to the options.expire to 0. I tested it with option.expire to 1, but still, in all cases, the bubble shows up even after adding to home screen.

  44. Is it possible to add a different message for users who are viewing through a Twitter app / QR reader app WebUIView so I can tell them “open this in Safari to add to homescreen” or something?

  45. It seems like, taht the “Add to home screen” Bubble will not resize for iphone users. It shows up very small. is there an option to change it, that it shows up in fit of iphone screen?


  46. Just wanted to compliment you on how professional this looks. Also is there a maximum value for the ‘expire’ option? I was wanting to set it so it reminds users every week.

  47. love this! – thanks, want to use it but have a small problem. when i use

    meta name=”viewport” content=”width=device-width, initial-scale=1.0, user-scalable=0, minimum-scale=1.0, maximum-scale=1.0″

    it scales up current site (posterous) weirdly so i have taken this line out, problem is the box is smaller and location arrow is wrong on the top now (ipod one is fine) – is there a simply way to adjust the arrow on the top for the ipad?

    i’m new to mobility sites but can hack things together ok. 😉

  48. One more question. I’m having trouble getting my custom webclip icon to show up. Is this because add2home.js controls this?

  49. I can’t run this web app in fullscreen mode because I need the back button to be available. If the app isnt running full screen, is it impossible to detect that the page has been added to the home screen? Thanks for your help, love the plugin.

    1. YouTube does this somehow, and I read that you can use a get http request to get the context root? This is all over my head, but would you know how to make this work?

  50. Didnt worked for me 🙁

    I changed the code for jqtouch like some suggestions here, but no way to make it work. Neither iPad, iPhone, nothing 🙁

  51. The script works perfectly, just one thing , I added my Homepage to the Home screen and once I revisit the Homepage I see the pop-up again, my site already has the meta tag :


    is there something else I need to do in order for the pop-up to not display if the shortcut is already added to the homescreen?

  52. Hi,
    It’s awesome!
    I was looking for something like this!!
    I donated you right now.

    Thanks a lot!

  53. Wicked cool code. Awesome. Is there a way to pre-create a “button” on the website that would be used for the button that gets placed on the iPhone, etc.? That is I would like to create a button graphic to be used as the icon for the “app launch” on the iPhone so it would be automatically used instead of what is generated…

  54. Hi Matteo. I absolutely love your script, buddy–thanks a million. It looks great on my blank test pages. The problem is I can’t get it to work on my full iOS web page, which utilizes iUI. iUI uses its own javascript code. My question is: Do you know of any way to make both iUI and Add to Home Screen work harmoniously? If you’re not familiar with iUI, do you have any tips with regards to how I may run multiple javascripts without conflict? Thanks.

    1. Nevermind. I solved the problem. I changed some code (From: document.body.appendChild(div); To: document.documentElement.appendChild(div);), and now it works flawlessly! I’ll be donating later today. Thanks again!

  55. Thank you, you saved me a lot of time. Your page was the first interesting one on Google and 15 minutes later I had it working on my webapp.

    1. it works for me. Maybe a temporary server error?

      UPDATE: the second time you load the page the icon doesn’t appear. That’s really weird, I cannot replicate on my server. Can you try to use relative paths instead of absolute ones?

      1. Hi Matteo, thanks for checking! Actually I used relative path at first but when the next day the icon disappeared I started investigating and changed to absolute path – same thing. It does the same thing on my local dev server and remote “production” one. Just changed path back to relative one on my local dev server – doesn’t work. Really strange. Any thoughts?

  56. Is there anyway to add a link to the pop up for going out to another page. I would like to use this pop up for directing people to another page so they can download my iPhone and Android apps.

  57. You write “iPhone does not support fixed positioned elements, so the message has to be relocated on each page scroll.”.
    On the site which uses a similar balloon, you can perfectly scroll the background while the balloon stays fixed. Maybe check how they do it.

    Nice work anyhow.

  58. hi, i have some question about script… in JS i’m new… so, i will discribe my problem…
    I have imported this script in my ASP.NET project, when i trying to compile and run my project, Visual Studio throws me an error –
    can you help me solve this error?

  59. Ciao Matteo,
    Everything is going well, I have put my webapp on Ipad, when click on created icon my website start in fullscreen, but when I try to click a link inside my site Ipad switch to browser and not stay in app! Why? Have you already find a solution for this strange behaviour? Thanks in advance! Luca

    1. you need to rewrite your links…
      i did in that case

      function navigator_Go(url) {
          window.location.assign(url); // This technique is almost exactly the same as a full [a] page refresh, but it prevents Mobile Safari from jumping out of full-screen mode

      right url

      ((HyperLink)sender).NavigateUrl = "javascript:navigator_Go('" + Request.ApplicationPath + "page.aspx" + "');"; //for Iphone
  60. the script works perfectly on ipad only in the portrait mode, but when I rotate the ipad or run the app on the landscape mode, the balloon shifts to the right of the icon, and it does not stand exactly below the icon, is there anyway to solve this problem?

      1. i have iPad 1 with IOS 4.3.5 version, the problem even exists when I run your simple example in the ipad simulator window, that’s why i don’t think it’s my app or ipad problem.

      2. the problem is solved! I just didn’t copy the Meta tag in your html page for keeping the page scale at 1.0, so it changed the page scale whenever i rotated the ipad, and therefore the balloon relocated in wrong spot.
        Thank you for the script

  61. Hi,

    I’m trying to dynamically include your script from within another javascript by injecting the script element into the document head. At the time I include the script, the load and domready events have already fired. I cannot get your script to work, because in this scenario the ready() and loaded() functions will never be called.

    Any ideas?

  62. Great script, have working fine, but is it possible to alter the default text that appears prior to saving link, or is it only available from the page Title meta?

  63. Thanks for the great scripts and detailed instructions – you’re site is a goldmine for a start-up’s shoe string budget! Donation sent, site bookmarked and knowledge paid forward to others!

  64. Can I load this script not on page load, but on button click? If it is posible, can you write short explatation? Thanks. 🙂

  65. if a web page is added once to home page and the same page is loaded on safari will it show the addtohome window or not?

  66. Most annoying script ever. How do you turn it off? I’m not going to fill my home screen up with web links. This script should be banned as it is invasive and extremely annoying.

    Not Impresed!

  67. Wow, I just put it on and added a quick call to our database to track users. I’ve have had over 100 this morning click the add to home screen button. Amazing results. Thank you!

  68. Is there any method to force the user to do the “Add to Home Screen” process? For example to dim the content of the webpage with content?

  69. Great script, it does not seem to work on iOS 5 though. Any thoughts on how to make it work?

    1. I’m suddenly not able to turn bookmarks into web apps on my ipad with ios5. I do the same “add to home screen” on the same sites I’ve already done it with and now they all open in Safari. The ones I bookmarked before still open in a web app. Is there some setting on the ipad that’s preventing this from happening? It’s not working on my iphone either.

  70. You mention: ” there’s no way to know if an user actually added the page to the homescreen.”

    Can you not use HTML5 local Web storage for this. I feel users will get a bit sick of this bubble appearing every few minutes even though they have added an icon to their home screen.

  71. Firstly, Thanks for all your hard work! I am new to programming and just trying to learn. I have the script running in a web app I’m working on but I can’t get the animation to appear just the text. Can you explain where you put the icons and the path to change to get them to appear for a complete beginner please?

    Thanks again

    1. Just worked it out! Only problem I am getting is on an iPad and iPhone 4 it adds the “add to home screen” icon instead of the app icon. On my 3gs running ios5 it works fine, any ideas please?

  72. Works really fine on Iphone.
    But what is with Android devices?
    Do you have a similar solution which also works with Android phones?

  73. Hi. Matteo.

    This is what i’v been looking for. However are you able to explain step by step the steps. Iv downloaded the plugin. Intending on putting it on a wordpress theme running a mobile friendly version already.

    Where should i place the plugin? what part of the folder?
    Where should i edit the code?

  74. Can you add a cookie when the close button is clicked, preventing the popup for ever showing again (until cookies are deleted)?

  75. I’ve noticed that when you add the bookmark to your homescreen, it puts a glassy overlay on top of the icon. Can this be avoided?


    1. Hi man,

      Yes you can:

      “In case you realized you don’t like the pre-defined rounded corner plus glossy effect at all, you will have to rename your file (or link rel) accordingly, replacing apple-touch-icon with apple-touch-icon-precomposed. In this way your icon will be rendered as you conceived it, with no further modification.”

      So here is the code:

  76. Really cool script. Added it to our bank’s mobile pages and all folks were impressed. Good job.

    If you’d find a chance to extend it to Android it would be even greater!

  77. Great Script!
    Another shout for Android support.

    BTW How do you add a web app to the Android screen? I can’t see an easy way to do it.

  78. I LOVE this script! I wanted to set it to just show on the home page. I looked through the responses here but the fix looked like it was from an earlier version or did not have an answer. If I set “expire” to “1” it won’t load the script again, even after, say 5 min. I’m kinda new so I am probably missing something elementary, Watson. Any thoughts? Thanks for your work!

  79. Does this work with iScroll? I downloaded it and tried, nothing happend, but an alert(); after everything was loaded appeared.

  80. What could I possibly be missing? Checked all paths, running with iOS 5.01 and won’t work on both an iPhone 4 and iPad 2. Added javascript alerts to the .js file and they pop so I know it’s finding it, but no page displays. Page also uses the iUi framework. Could they perhaps be conflicting?? What about 5.01 iOS? Is that tested? Is the UTF-8 thing required? Can I add that as a META tag to the page instead?
    Sorry so many questions but I’m trying to debug this.

      1. bodyElement did not work. Finally got it to drop now but only by commenting out all the iUi code. There definitely is a conflict and I don’t know how to create a workaround.

      2. Have narrowed it down to a specific CSS setting in the iUi code. Any idea why this conflicts with “Add To home”?

        body > *:not(.toolbar) {
        display: none;
        position: absolute;
        margin: 0;
        padding: 0;
        left: 0;
        top: 45px;
        width: 100%;
        height: auto;
        min-height: 415px;
        -webkit-transition-duration: 300ms;
        -webkit-transition-property: -webkit-transform;
        -webkit-transform: translateX(0%);

      3. I’ve got the same problem. Trying to implement with iui and the ‘body > *.not(toolbar)’ css breaks it.
        That section is fundamental to how iui works, so it’s impossible to change it. It’s how iui hides the different pages and transitions to them.

        I’m also using iscroll, but this doesn’t seem to be a problem.

        Would be forever grateful if there’s a fix for this!

        Cheers, Tony.

  81. Solved it!

    Add the class ‘toolbar’ to the add to home javascript and it works. Still some small css issues, but essentially it works.

    This is the line in addtohome.js, add the bold bit:

    div.className = (isIPad ? ‘ipad’ : ‘iphone’) + (touchIcon ? ‘ wide’ : ”)+ ‘ toolbar’;


      1. Hey, just try to use our thing: add “display: block !important;” to the #addToHomeScreen and I now have the add to home screen showing 🙂 sweet ! But it extends on all the height of the page…. So not the best fix.. If anyone have ideas. I am trying to fix it too

  82. Hi,
    I have a problem;
    When opening the front page via the icon on the home screen, all links on this site is opening in a new safari window. That is annoying, not possible to use back button..
    Any solution?

    You can test it here:

  83. Following up to post on 11/23… hoping ‘Tony’ can explain exactly which line to put display: in CSS to solve the problem with iUi framework conflict. I got it to work but the text spilled out of the bottom of the balloon so still broken. – Thanks in advance.

  84. Hi,

    The fact that the current version can’t be included dynamically makes it impossible for me to use it. You announced a 2.0 version 2 months ago. I do know you are probably doing this in your spare time and this script is a free giveaway. Is there still a chance 2.0 will be out anytime soon?


  85. Great script ! Thank you !
    I will use it for my next wep app 🙂

    I have only one question : is it possible de change the url shortcut ?

    Adress of my web app : with your script
    Adress when the user click on the shortcut :

    Thank you for your help.

  86. So cool! I’m running iOS 5 and the height of the box extends all the way to the top of the page. I can’t figure out how to fix that. Any ideas? Thanks so much!!!

  87. Hey, I’ve been using this AWESOME script on a clients site for a while, but I am just now getting around to worrying about the size of the box. I know I can change it in the CSS but is there a way I can just resize the balloon to fit the screen (proportionally appropriate)? Right now, when you load it is so small you can hardly read it, is there a way I can resize it without changing every width/height size in the CSS?

    1. I would also like to know how to do this….it would be a great option to add.

      Any suggestions?

  88. Hello,

    first of all: really nice job!

    Now, I’ve got a problem: I’ve got this script working finally but it shows an “Approve” mark when this Add to homescreen script comes up.

    I’ve not tested it yet in the english text but i’ll translate:
    Install this web app on your %devic(APPROVE MARK)e
    so basically:
    Install this web app on your iPhon(APPROVE MARK)e

    I don’t have any idea how to fix it.


  89. Love als the script! Good work!
    I have a problem such as Ken. Only in this case with jQTouch framework. The script works great without jQTouch code so also in this case there’s something conflicting.
    Any solution? Thanks in advance.

  90. This script is really nice and easy to use, thanks. You say above that there’s no way to tell if a user has added the app to their home screen yet the FT app somehow knows.

    If you visit the app in safari it says “You’ve added the FT Web App to your homescreen but are not using it. Launch the FT Web App from your homescreen to get the best out of it’s features and content.”

    Any idea how they can do that?

  91. Great work Matteo!

    I was able to implement it without much trouble at all. I did notice, that once I added the code, the accented characters are not being interpreted correctly. I’m trying to debug it now.

    Thank you for sharing!!!

  92. Works perfektly! Is there a way to enlarge the close icon?? Have tried in the css, but that doesn’t make the icon bigger..

  93. Is it possible to send notification messages to standalone iPhone web apps?

    Thank you

  94. Hie,

    Thanks so much for this very good script.

    Also, I have a problem to implement it correctly.

    When I use it alone in a page without effect js and css, everything is right.

    But in my iphone page, it does’nt. Do you have an idea please ?

    Thanks, Olivier

    1. Hie

      I think the problem is coming from IUI in my page. Is there someone with an idea ?
      Thanks so much for this excellent work.

  95. This is a great plugin for my site! I am having just one issue. Once it is launched on the homescreen and you hit any link it launches again in safari.
    Am I missing something or doing something wrong?

    Other than that it is great!

    1. @CHAE: You also have to add this to the head of your website:

      Then Web App will not start again in safari

      1. Tobias,

        Thanks for the reply, I have added this to the header of my site template but still opens up a new Safari window.
        Also, is there any way I can customize the add 2 homepage text? It is pulling the title text from my website, and it does not start with my company name.


  96. I found this code, but where do I install this?
    (function(a,b,c){if(c in b&&b[c]){var d,e=a.location,f=/^(a|html)$/i;a.addEventListener(“click”,function(a){;while(!f.test(d.nodeName))d=d.parentNode;”href”in d&&(d.href.indexOf(“http”)||~d.href.indexOf(,e.href=d.href)},!1)}})(document,window.navigator,”standalone”)

  97. Hi there !
    Great script. But it doesn’t seem to work for me. I built my app with iUI and experience the same problem Mr.Olivier (above) seems to. Whatever I try, I can’t seem to get it to work. Do you have any information about your script together with iUi ? Cheers and thanks,


    1. Hie, I fixed the problem with IUI.
      Place a display:table in addscreen css wire. Reset with margin:0 and padding:0 +++
      Very good source.

  98. It’s probably something really simple but i am a newbie and can’t figure it out. the message drops down from the top but it shows the text only…no bubble, no touch icon…what is the problem?

  99. I am using this script. It works fine but popup baloon is coming everytime even if i have added to home screen. Please give me the solution ASAP.

    Thank you.

    1. Hmm, “Please give me the solution ASAP?” I think you should say “Thanks for giving me a great solution”. Very rude demanding that someone should give you something for free, when you already got most of it for free?

      Anyways, Matteo, thank you for a great script, I am looking at a cookie based solution but it is not easy.

  100. I’ve added the basic script to my mobile site, but I just dont get the popup. Can anyone suggest what I’m doing wrong?

  101. All my visitors/users are Danes, so I would like to present the message in Danish.
    However, if the visitor has an iPhone with English as the device language, then then instruction should still be “Add to Home Screen” (with the rest in Danish). Is that possible?

  102. Hi Matteo, thanks for this fine script. It’s up to the point, simply perfect.
    You suggest to use “one of the many include/require/load javascript libraries” for conditionally including the script. I tested this with yesnope.js, but the async loading leads to problems with the initialization.

  103. Hey, awesome script, works like a charm.
    One question though: to hide the URL bar, I did this:
    body onload="window.scrollTo(0, 1);"
    So now when I show the bubble it’s 40px too high, but when I move the page it “jumps” down to its correct position. Any idea on how to solve this?

    1. Also, the X-Button doesn’t seem to work for me (unless I’m doing something wrong).

      var addToHomeConfig = {autostart:false,

    2. I can change it if I edit this line: = options.bottomOffset + 'px';
      to = (options.bottomOffset - 60) + 'px';
      But as soon as I scroll or pinch, it “jumps” down. Any idea how I could catch these 60 pixels?

  104. I’m having the same issue as Phil (above)

    Most mobile suites like to hide the address bar these days. Taking this into account would make this awesome. I hope there is a fix for this.

  105. One possible solution I can think of is to scroll the page via javascript just before showing the bubble, but I’ve been trying to do that unsuccessfully so far.
    A different approach (not the smartest one, most likely) would be to check if the page’s been scrolled manually (e.g. with jquery’s .scroll()-event) and then remove the “-60” from the code. I’ll give that a try.

  106. Having trouble adding this to a WordPress-powered JQM site. Anyone know how to include this properly? (I’ve tried adding to header.php using wp_enqueue_script to no avail).


    1. Im adding my custom.js to the headtag, then within it I have the code that calls the add2home bubble.

      It is not possible to only show this bubble at the JQM home indexpage, it will be displayed on all subpages too.

      You must define the variables before the section that uses document.write to add the script URL’s, and because of this you can not use the pagecreate events to activate this script and have it showing only on JQM home page.

      Best regards Victor

  107. Really great piece of code, thank you very much! I can’t wait ’till you add Android support – Will be so awesome!

  108. Dang – I wish you hadn’t published this. Espn mobile site added it and now I get that annoying ballon each time…

  109. How do I apply this to icons on my site. my teacher asked me to add the code that would add a link to an icon so that when you add it to the home screen it makes the icon on the devices
    im not sure what the link is that I need to add to my icon.

  110. Hey,

    Is there a way to customize the homescreen icon that will appear on the user’s device after they save it to homescreen?


    BTW Amazing script. Love it.

  111. Okay, I got a problem. I put this code in the index.php, just before thr tag.

    var addToHomeConfig = {
    animationIn: ‘bubble’,
    animationOut: ‘drop’,
    message:’Install this web app on your %device: tab `%icon` and then Add to Home Screen.’

    Also, I uploaded through the FTP the “apple-touch-icon.png” (57×57) to the root. Also to the root I installed the folder (next to the folder “css”) “js” and put the “add2home.css” and the “add2home.js”.

    The message comes up, but the bubble is transparent, the apple-touch-icon is missing and the %icon won’t show up. Also when manually installing the web app, the apple-touch-icon doesn’t get shown…

    Who can see the mistake? I thank everyone that can help.

  112. I’m having an issue getting the close button to work. I’ve tried it using your live demo on my iPhone and iPad and when I touch the “x” nothing happens. Any ideas? Thanks!

  113. Android, Android, Andoird!

    And a merge into the querymobile-environment, maybe they have some energy in realizing for even more mobile-browser 🙂

    Thanks very much anyway. 🙂

    1. Android doesn’t have a full screen mode actually. The script itself already works on Android but the procedure to add a bookmark to the homescreen is not straight forward as it is on iDevices

  114. Has anyone got this working using WPtouch Pro for WordPress? I tried adding the code to the header.php file of the theme being used but it’s not working at all. I put all the files in the root of the site and used the following:

    var addToHomeConfig = {
    animationIn: ‘bubble’,
    animationOut: ‘drop’,
    message:’AB Playbill. Your device is an %device. The action icon is `%icon`.’,

    if (‘standalone’ in navigator && !navigator.standalone && (/iphone|ipod|ipad/gi).test(navigator.platform) && (/Safari/i).test(navigator.appVersion)) {

    1. I should learn how to use this properly. Here is my code:

      var addToHomeConfig = {
      animationIn: 'bubble',
      animationOut: 'drop',
      message:'AB Playbill. Your device is an %device. The action icon is `%icon`.',

      if ('standalone' in navigator && !navigator.standalone && (/iphone|ipod|ipad/gi).test(navigator.platform) && (/Safari/i).test(navigator.appVersion)) {

  115. My comment didn’t appear first time sorry if this is a reposts

    Is there a way to dim the background during the 10 or so seconds the add2homescreen popup is displayed


  116. Very nice work, thanks!

    Just wanted to add that it’s not always necessary to mess with the .htaccess file to set the character encoding.

    Most of the time (maybe always?) it’s enough to add


    to the script tag.

  117. Works great, thanks. One problem, it the bubble reappears after I add it to my home screen. Any thoughts? I have tried the hash trick and

    Neither have works,


  118. What a great script! Best way to make people aware of installing webapp! I would like to contribute with czech translation. “cs_cz: ‘Pro instalaci aplikace na Váš %device, stiskněte %icon a v nabídce Přidat na plochu.'” I’m not sure if this is literal translation, but its user-friendly czech sentence.

    1. Damn! I made this with correct utf-8 codes, but i didn’t think that it will write corectly with diacritics right on the page. PLS find the correct UTF codes

      1. Matteo,

        I’m using godaddy linux hosting. I’m trying to make this work but for some reason it looks like it’s not recognizing the CSS because it drops in as a text that says

        Install this web app on your iPhone: tap and then Add to Home Screen. x’

        But not the normal bubble that iPhone 4S shows.

        I followed all the instructions but for some reason I still cannot get anything but text dropping down. Sorry if this seems like a dumb question but I’m a bit of a newbie at all of this and just trying to learn.


  119. I’m using godaddy linux hosting. I’m trying to make this work but for some reason it looks like it’s not recognizing the CSS because it drops in as a text item rather than a bubble.

    I put he css file in the same folder as the .js file and it still didn’t work so I then put the css file in the main directory and that still didn’t work. Sorry if this seems like a dumb question but I’m a bit of a newbie at all of this and just trying to learn.


  120. Hello Matteo,
    Thank you for this handy and versatile script. It did save my day and I tried to make a small donation, but it was not clear how to donate in US dollars. I admit I am clueless about euros. Please advise.

  121. Here’s a fix for a problem I ran into on jQuery Mobile 1.0.1 using the “touchOverflowEnabled: true” option. When set to true, the “add to home” bubble would drop down too low (below Safari toolbar). I was using touchOverflowEnabled for fixed toolbar support, but jQuery Mobile 1.1 deprecates touchOverflowEnabled in favor of real fixed toolbars so soon will be a non-issue.

  122. Perfect script, thank you! Just one serious problem: If private browsing is activated in Safari, the javascript returns an error as the client state cannot be stored in client database (I guess). Maybe this should be investigated in, to not display the ballon if private mode in browser is enabled. I could reproduce the problem on ipad2 and iphone4s.

  123. Great script and easy to use. I removed the website sizing code because both the iPhone and iPad resize to suit their screens

    Other than that the script is great, just what I was looking for.
    Thankyou for a great script I use this on both my & sites

  124. Great script and easy to use. I use it on both my .com and .mobi sites.

    I removed the meta name=”view” from the coding because bith the iPad and iPhone resize to suit.

    Thanks for some nice coding

  125. I’m having an issue where after I’ve installed the web icon, then I return, it prompts me to re-install. I would prefer to never show the “add to home screen” once the the icon has been installed.

    I have added the following to the header

    but I’m still getting ask to install the icon.

    help is greatly appreciated. Fantastic script by the way.

  126. If the app hides the url bar then positioning ends up being wrong. For example if the following code is used.

    setTimeout(function() { window.scrollTo(0, 1) }, 0);

      1. Thanks for the code, very useful! Do you have any further information on how to solve the minor issue with hiding the address bar? I’m pretty new to .js so any guidance is much appreciated

      2. Set the autoload to false. Then add an onload event and place the function inside a 1000ms timeout:

        function loaded() {
          setTimeout(function () {
          }, 1000);
  127. I was using the earlier version with success. HOWEVER, when using v2.0 I notice this problem:
    — the icon (add to home screen- the box with arrow) does not show in the bubble.
    Feel free to look at my site.

  128. Is there any way to adjust the display frequency of the bubble with something other than minutes? Could you display it, say, every 15 (or X number of) page loads?

  129. I have added a ‘add to home screen’ code to my standard website (its not optimised for an iphone) to show message about downloading my iphone app. There is no need to do an iphone optimised site (for my website) but I do like the idea of them seeing this baloon offering to download the app from the store.

    The problem is that it shows tiny and practically impossible to see. Is there any way to make it full size and not reflect on the size of my page?

    1. add the following to your header.php and the files in the js folder.

      <link rel="stylesheet" href="/js/add2home.css" type="text/css" media="screen" />

    2. I cannot seem to get it to work in wordpress, I have tried it with a few different themes, but it won’t work. I have copied the css and js files into their own directory, within the theme, but still no joy.

      Am I doing something wrong.

      1. never mind, I got it to work eventually. had to use
        <link rel="stylesheet" type="text/css" href="/js/add2home.css”>

        <script type="text/javascript" src="/js/add2home.js”>

      2. <link rel="stylesheet" type="text/css" href="/js/add2home.css”>
        <script type="text/javascript" src="/js/add2home.js”>

      3. looks like comments is stripping the php out,

        <script type="application/javascript" src="/js/add2home.js" charset="utf-8">

  130. Great work!… but… the message keeps showing for every page of the site even after added to the home screen… does that happen only to me? Am I doing something wrong here?

    1. Only load the script if the page is not in webapp mode, then it will not load at all when the page is started from homescreen. Example of javascript:
      if ((“standalone” in window.navigator) && !window.navigator.standalone){
      document.write(‘var addToHomeConfig = {‘);
      document.write(‘ animationIn: “bubble”,’);
      document.write(‘ animationOut: “drop”,’);
      document.write(‘ lifespan:10000,’);
      document.write(‘ expire:7200,’);
      document.write(‘ touchIcon:true,’);
      document.write(‘ returningVisitor:true,’);

  131. I just want to simply use a PNG file to drop down. Nothing else. What code should I use for that?

  132. Love the script dude.

    I just wanna know if theres an iPad update coming, even tho I’m using an old iPad (1st gen) the popup seems a bit off. It’s right on the edge of the screen when using both iPhone 114×114 Retina icon and standard iPad 58×58 icon. It looks awesome on the iPhone but looks awful on the iPad.

    Will this be fixed in the next update or do I need to find a workaround?

    Many Thanks!

  133. What is the best way to determine whether the balloon is currently displayed?

    I want to use addToHome.close() to make sure the balloon is hidden when the user takes certain actions. But it seems that if the balloon is not displayed, calling addToHome.close() generates an error.

    TypeError: Cannot call method ‘querySelector’ of undefined”

    I assume it’s just because close() should only be called on an open balloon. Or am I perhaps doing something else wrong?

    That question aside, this plugin is working great for me.

  134. Hi there,

    this is a great script!!!
    Works perfect!
    I’ll let it run for a while and than donate a bit – for sure!

    Greetings, KH

  135. Wonderfull script. Very easy to integrate and very ‘powerful’ too. Thanks. Because of this it’s a pleasure to show a little financial support.

  136. Hi, I am going to sounds like an amateur here, but where do I need to install the script – ie. I get where to insert the code in the page, but do I need to also upload the javascript file onto the host server and if so where should I put it? And how should I nominate the path in the code?

    1. the naming it’s up to you. if –for instance– you upload the script to your server under the addtohome directory, then link to the files like so:
      <link rel="stylesheet" href="/addtohome/add2home.css">
      <script type="application/javascript" src="/addtohome/add2home.js"></script>

      1. ok, thanks.
        The script file downloads as a zip file. Do I need to extract all the files from the zip file first before uploading it to the server? Also, do all the files in the zip file need to be uploaded or if not, which is the file to upload?

  137. Hi there and thanks for this great script.
    Is there a possibility to open such a little box when loading which opens a or .html as popup and closing as well?

  138. Doesn’t resize properly on iPhone. Very small hard to read. Is there a fix for this? iOS5 problem maybe?

  139. I would like it more if it would display on the whole Screen..
    Like a “big” Message.

    If you have a big site, it’s just very little.

    Can you help me?

  140. There seems to be a problem with localStorage.setItem, i think it’s a security problem, maybe only iOS5, so it’s preventing the X (close), returnungvisitor and expire functionality to work correctly.

    1. could you please test my online demo and verify if that dialog is actually too small? I suspect people having trouble with balloon size don’t use initial-scale:1

  141. Hi, good morning…

    This script is awesome, all settings tested and working perfect, but I have a little issue, after “add to home screen”, all my links open a new safari tab, this is my deb site:

    Any ideas????

    Thanks a lot…


    1. full-screen for just the home page and browser-bar windows thereafter is just the way iOS web apps are formatted

  142. Hey. I can implement this ( ADD TO HOME SCREEN) module into my mobile jomla website ..? If I can how do I do? .. I have tried a little back and forth but no luck .. I’m far from good at making websites. So I hope there’s someone who can help me … thanks in advance

  143. Hi

    On my iphone the website is too big and needs to be resized to fit the screen but the buble is the perfect size.

    We did have it working the opposite way where the website was resized to fit the screen but the bubble was too small, then we added the following code and it went the opposite way as stated above. Can you suggest a fix. FYI great feature.

    My website link:

    <meta http-equiv="Content-Type" content="; charset=” />

  144. Hi there, above all thanks a lot for you great script. However I am experiencing a little issue, the same as HomeroMx.

    Each page I open from the WebApp open in a new safari tab, any idea to stay in the full screen webapp ?

    Thanks in advance.

    1. Pretty sure that the full-screen feature for just the home page and browser-bar windows thereafter is just the way iOS web apps are formatted.

  145. Hello, I want to donate to you but I REFUSE TO USE PAYPAL. Oh well, your loss. Moneybookers is great, so are PayMate. Offer something other than PayFuck, eh, I mean, PayPal, and I’ll be glad to donate 20 bucks!

      1. sorry, but i’m not going to sign up to something just for one donation. i’ve shared on facebook and twitter. i love this script – it used to work for me i know, but i have no ios devices to test on now so i’m just going on faith it’s working on my sites. i’ve tried testing in safari with the ua set to iphone or ipad under the developer menu but it doesn’t show. hope it’s working!

  146. Is there no option to say: “once a user dismisses the bubble I don’t want to show it again” ?

  147. Great script Matteo. Works perfectly so far. Any idea on when Android support will be added? Days? Weeks? Months? no pressure haha keep up the good work!

  148. First of all, great script! I use it on multiple sites and works like a charm.
    However, I’ve added it on a new site of mine and the bubble keeps returning, even though I ‘install the webapp’. Any idea what could be wrong?

    Here’s the code (same for all my sites):
    var addToHomeConfig = {
    touchIcon: true


  149. does this work in safari when under developer settings the ua is set to an iphone or ipad? i’m trying to test like this and it just won’t work.

  150. I cannot get this to work on my wordpress powered blog. I have unzipped and uploaded as is to the plugins folder and added the following in header:

  151. It wouldnt let me post the code so where it says path too I have used /wp-content/plugins/cubiq-add-to-homescreen-508e479/style/add2home.css AND /wp-content/plugins/cubiq-add-to-homescreen-508e479/src/add2home.js

  152. Hi

    Thank you for the great script.

    I’m having a similar problem to Chris.
    I have set apple-mobile-web-app-capable to yes, but, even after adding my site to my homescreen, I still get the bubble appearing on every page. I hav ethe code below in my . Am I doing something wrong?



      1. Hi Matteo

        I can’t post a link to my client site as I’d get into bother 🙂

        I did however upload your examples to a test server, which seems to be doing exactly the same thing on my iPhone 4:

        When I add the link to the homescreen and then open Safari again and refresh the page, the bubble pops up again.

        I did just update iOS to 5.1.1 (9B206). Could that be anything to do with it? Or am I missing something here?

        Many thanks


      2. Thnaks for looking Matteo.

        I just tested it on my partners iphone 4. I load the page, no bubble appears. I close the browser and re-open it, refresh the page and the bubble appears as expected. I then add the page to the homescreen. I then re-load safari and refresh the page and the bubble appears again.

        I’m out of options.

        Thanks again.

      3. Hi Matteo

        Sorry, should have said, I get the same results with and without the cache being cleared. I’m clearing the cache fully under settings.

        I just tried your link on my iPhone4 and iPad2 (both with latest update):
        and get the same result again. The bubble popus up after the link has been added to the homescreen.

        I only have access to 2 iphones and an iPad2 I’m afraid.

        Driving me potty.

        Many thanks for your help


        1. I totally need to see a video of this 🙂 Really I cannot replicate on any of my devices. Please remember to completely kill the browser (remove it from background) before clearing the cache. Even better try to reboot your iphone.


  153. Doh, wouldn’t let me post my code either, but I set the web app to enabled etc. Should I add that before or after the call to the js and css?



  154. I have the tool embedded on a page where there is also an iframe that loads google mapps.

    Somehow it’s using the url of the iframe rather than the url of the page itself as bookmark link…..any ideas why? thx 🙂

  155. We are using iPad. When we open our web site in Safari we have ‘Add to Home’ pop up. If we Add it to Home we get an icon on the iPad screen. If we close that session and again open it in Safari we again get ‘Add to Home’ pop up. How can we avoid that. We checked the same functionality for other site e.g. espn. For that site the ‘Add to Home’ pop up does not come back once it is added to screen on iPad. Is there any way to find out that whether this site is already added on the screen of the iPad?

    1. you can make an educated guess, but it’s not bulletproof. On ESPN they probably set a cookie if you come from the URL that shows the balloon (instead of simply

      1. Hi Matteo. Thank you for reply. One more question, if we are able to add web app on the screen of iPad (with the help of javascript), then there should be a way to find which web apps are present on the iPad screen. Is there such kind of javascript/jquery to find out web apps on iPad screen.
        Thanks in advance.

      2. Hi Matteo, did not find reply button below your latest comment. So asking my question here. When we click ‘Add’ button from pop up to add app on iPad screen at that time which event/function is called? Can we handle/update that event/function? Please let me know as we require it urgently.
        Thanks in advance.

  156. Hey, great script though it seems to have a problem with iOS 5.1.1 which causes the icon and splash screen to fail to load.

  157. Hi Matteo, first of all thanks for the nice script.

    We have a problem with the following:

    The bubble opens on every page, because we are using a cms. But this is ok.

    Now if you add a page to the home screen, the bubble will not appear on this particular page, but on every other page.

    It would be nice if the script only added one particular page to the home screen (the homepage) and does not appear on every page after that.

    Is this possible or do we have to only include the script on the homepage and not on the following pages?

    Thank you!

      1. Thanks for your answer, of course this JS just points to an iPhone feature, so the url cannot be changed. Your answer is the solution we are looking into right now.

  158. I love this script! I would like to customize it so there are different apple-touch-icons for each college. Is that possible? I’ve tried adding another icon called apple-touch-iconcc.png, editing css and js file but it always uses the standard apple-touch-icon.png. Ideas?

    1. maybe you have caching issues? Remember to place just 1 touch icon per page per device and add a “scrambler” to the image name to destroy cache (eg: apple-touch-icon.png?v123)

  159. «If the user intentionally closes the balloon, it won’t show up again for all the duration of that session.»

    How I can owerride this?

  160. If you want to go back to the first page when attempting to move to the next page on the last page you can place this in your onScrollEnd function.

    if (tmp) {
    this.currPageX = 0;
    this.scrollToPage(0, 0);
    tmp = false;


    if (this.x == this.maxScrollX && !tmp) {
    tmp = true;

  161. Thanks for this great script. Is there any way to prevent balloon from appearing from the website view (not from the webapp) if the app has already been added to the home screen?

    1. you can change the page hash when the user reach your site, if user bookmarks the hashed page you set a cookie which prevents the balloon to appear. Not 100% failsafe though

  162. I need to check, in an URL following to the one where we ask the visitor to install icon, to check if it is accessed by the icon app.

    I mean… if user does not install shortcut, detect it, and redirect to a page saying something like “you need to install shortcut to access this site”.

    Is it supported somehow?

  163. Has anyone had a chance to test this on iOS 6?

    Are there any changes coming with mobile safari that will impact this?

      1. iOS6 has the share icons in a slightly different place in mobile safari. Beggars can’t be choosers, as the saying goes, but do you have any plans to update the script?

  164. Hey, this code is exactly what I need, but I’m having trouble setting it up. How do I install the javascript to a website hosted on Hostgator / WordPress? Thanks for the help, I’ll donate if I get a helpful answer.

  165. Thanks for the script, it’s perfect except for one issue – the balloon image overwrites my favicon so instead of using my favicon on the homescreen it uses your balloon image. How can I correct that? Many thanks!

    1. Sorry, missed the WEB APP CAPABLE section. Will implement that immediately. Thanks for thinking of everything!

  166. Awesome script! Thanks for creating this.

    I am having one issue with the iPhone 4/4s only in which the bubble displays in the middle of the page but and doesn’t lower until the user scrolls. As I said this just seems to be an issue on the 4/4s. Any idea why?

      1. Has anyone found a solution for this? I added code to remove the address bar:
        window.scrollTo(0, 0)
        And since then, it shows up in the middle of the screen.

  167. Hi Guys,

    thank u for that beautiful script. Attention, i am new in coding.

    Please, i have a Problem with the touch icon, can anybody help me ?

    i changed the header like i should.

    but i want to change the icon as well, so i insert this line in the header.php:

    and put the icon on the servers.

    Now, so my hope, the bubble should show the icon !?

    Am i wrong ? Couse it doesn´t show up.

    Any help ?

    Thank u very much

  168. Your script will not run on iPhone 4S Safari browser with private browsing enabled on a jquery mobile site.

    It causes the whole page to never load and I get this error in the debug console:

    Javascript: Error
    QUOTA_EXCEEDED_ERR: DOM Exception 22: An attempt was made to add something to storage that exceeded the quota.

    I’m using the autostart:false setting and I’m running the script myself with

    I had to use a try catch around the so that it wouldn’t stop the website from loading. You should make note of this in your “AutoStart” section of this page.

    try {;
    } catch(e) {
    alert(“disable private browsing”);

    1. Indeed, private browsing prevents localStorage from working, so it throws the error. I would be nice if the script supported that… 🙂

  169. Two questions:

    1. Is there anyway to rename the “page title” that shows up when they click the add-to home screen button? That is have it pre-selected and filled in to something the webmaster specifies? My site defaults to something that is too long (> 11 characters).

    2. It seems as though the javascript recognizes that it has been installed on the homepage, but every sub-page will ask if you want to add this to the home screen (wordpress site).


  170. Hi, is there a way to link the touch icon to another homepage? So if you add it to your homescreen the icon should open for example the app store ore something else.

  171. I’m having a wicked frustrating time getting this to play nicely with my scrollbar hider code. It seems to display the balloon “too high” on my iPhone4. I adjusted the bottomOffset to -46 it works. But then looks horrible on iPad.


  172. Thanks for the script!

    How do you get this to work on non mobile devices (desktop)?

    I see you can bypass the compatibility checks by calling but this still doesn’t work if you’re on a desktop. I want to be able to see it on my desktop so I can tweak the CSS with dev tools.


  173. How to enable this on Safari only? What if visitor is using Chrome, Opera, Skyfire etc. on their iOS device?

  174. Doesn’t work if your home screen is “full”.
    That is, if you have 11 screens full of 4×4 apps.
    That is, if you have 176 apps.
    I have too many apps.

  175. Many thanks for the excellent script. Excellent touch for our site that we’ve just put live!

  176. super thanks for the great effort and amazing bubble prompt.

    i have a question in mind though it might out of the topic!

    is it possible to restrict adding to home screen function, for only the index page ?

    thanks again.

  177. Wow. This is go great, it really took my bands mobile site to the next level and it simply looks fantastic. Very easy to set up and add to your existing code. Thank you very much guys!

  178. As Ryan said, when you remove the address bar to make the viewport bigger, the balloon doesn’t go all the way down. When you switch to landscape and back to portrait, the balloon is at the bottom, where it’s supposed to be. Putting in a negative offset messes everything up so I don’t want to do that.

    Could you adapt your script to support this please?

  179. Its a great script. I have recently used this script but find some issues.

    Would you please help me out?

    When I test on iPhone and call the web app from the stored home-screen button then first page opens correctly, but then all following pages open again on the web-browser.

    how to close this box – nothing happens by clicking on the X

    How to add logo when web app will be stored on the homescreen : now there is a screenshot with the actual screen


  180. Where do we put it if we are using a wordpress site, hosted on wordpress. I have an index.php but I dont know where to add the js head code mentioned above since its not an html page.

  181. Hi Bro,

    Very nice script and thanx for providing it.

    Some guys, stole your code and is selling it at Warrior Forum. His add2home.php has this “/*!
    * Add to Homescreen v2.0.1 ~ Copyright (c) 2012 Matteo Spinelli,
    * Released under MIT license,

    Here is the sales page


    1. Actually, they didn’t “steal” the code and followed the licensing rights that they were given to the software.

      They had every right to modify and include the script in their software per the license agreement –

      1. go for it, that is all what the MIT license is about. you could make a small donation to the project if you are so inclined, or maybe contribute to the code with your modifications. You know, just to keep the good karma.

  182. Hi Matteo,

    Thanks for the brilliant script!

    One point which has come up numerous times in these comments, but has yet to be answered, is that of the ‘X’ (close) button. It does not (always) work.

    I say does not ‘always’, because the exact same code DOES work on my iPad 2, but does NOT work on my iPhone 4 OR new iPad (3rd gen). As I said, this issue has also been raised by a number of other users so it is not just me.

    I am afraid I cannot think why this would be, but I think it definitely needs some attention!

    Thanks in advance,


      1. I am using your source code as is. Are you saying it is working for you on retina devices?

        I cannot test it on the iPhone 4S, but I assume it would be the same as on my iPhone 4 and new iPad.

        (RE your suggestion, I tried assigning the trigger to part of the text but it also does nothing and that can’t be a sizing issue?)

  183. “The MIT license this was released under permits use of this code in proprietary software such as this WordPress plugin.”

    You can’t have ‘proprietory software’ for a wordpress plugin. WordPress is GPL and all themes and plugins should follow the licence. While you can sell any plugin/theme you cannot stop anybody doing whatever they want with your plugin so that rules out ‘proprietory’ doesn’t it.

  184. Hi would you mind sharing which blog platform you’re working with? I’m going
    to start my own blog in the near future but I’m having a tough time choosing between BlogEngine/Wordpress/B2evolution and Drupal. The reason I ask is because your design and style seems different then most blogs and I’m
    looking for something unique.
    P.S My apologies for getting off-topic but I had to ask!

  185. Hi…my questions is ¿how I can detect if the icon exist in the home screen?

    I need to show the message “install the app in your…” only when the icon does not exist…

    thank you for your help… 😀

  186. So i can use this script for free on my Website? I only have to write ADD2HOME by Matteo Spinelli?! THX

  187. Hiya,
    Great piece of code, congrats!

    Is there a way of forcing the Add to home popup to appear before the DOM is fully loaded? As in immediately as the page opens up?

    I’m using it in conjunction with a preloader script for an offline web-app, and it would be great to have the prompt open up even while the preloader is running, and not wait for all of it to load up?

    I’ve tried adding in at various points, but that didn’t work as planned…

  188. Has everyone been able to successfully get the touchIcon to show up? Mine is just an empty box on my ipad no matter what I do.

  189. Really great script. Quick note about use with jQuery mobile – the strange mid-page floating bubble problem will occur (until you scroll when it then corrects itself) unless you make sure to define the following in your css:

    ui-page {height: 100% !important;}.

    1. And when I said

      ui-page {height: 100% !important;}

      what I really meant was

      div.ui-page {height: 100% !important;}

  190. Would be great if someone made this into a plugin… Would go mental in terms of popularity 🙂

  191. I would like to ask if I can provide two message of different locale to be shown base on the user setting. (en_us and zh)?

  192. I think that the problem with de X button is the private browsing in the device. I had it active and the X didn’t work. I modified the function close in the js file and put an alert there. The alert came up after the default 20 seconds… Just like if the call was blocking somehow.

    Then I decided to switch off private browsing and the alert appears just when I click the X button, and the balloon is closed. Maybe it fails to write whatever it’s described at ‘More power to the user’ when private browsing is active.

    Just my 2 cents.

  193. Hi, this is absolutely brilliant work done by you.Thanks a ton.I was wondering if it is possible to call the “arrow dropdown” once you touch the bubble.

  194. is there a way to easily increase the size of the icon and close button for the popup?

  195. The balloon is still loading even the user add it to the home screen. Is there a way that the script is detecting if the mobile device already add it to the home screen so it will not show again? Thanks.

      1. I’ve read the docs multiple times and I can’t find it either? How can we enable this because it’s really frustrating.. But very nice plugin! 🙂

      2. Curious if there was ever a solution for this, I’m having this problem of it showing up even though it’s been added to the homepage

      3. This happened to me because I was manualy triggering the notification using the command. Unfortunately this action still opens the message even if a shortcut has been added.

        I worked around it by storing a flag in localstorage if the application is launche in standalone mode. If the flag is set, I am not calling the show command.

        Hope this helps.

  196. Good morning, excuseme for my bad english but can’t use this script in my page. i don’t know why.
    maybe for i have joomla cms? the style add2home.css it’s copied in template.css and the script it’s copied in my index.php.

    i don’t understand why no show the ballon. thanks

  197. I need to change the background colour of the touch icon. It’s light grey now. Where can I do that in the CSS?

    I have a transparent icon with some white text and iOS automatically adds a black background when it creates the app icon for the home screen. I’d like this dialog to show the same icon.

  198. I found a problem with the script. Explorer 8 throws an ugly out of memory message.

    The message is “out of memory on row 7”.

    I know Explorer 8 is slowly dying but it’s still at 10% so I need to fix it. Can something be done to the script or can I hide the script from IE8 somehow?

    1. I found the problem. IE8 chokes on the CSS file, not the script. So I hide the CSS from IE with this:

      script here
      css file here

  199. Thanks for the great script. One question: where is the add-icon.png in the javascript or css? I want to modify that image, but I can not find it. Many thanks for any reply!

  200. Hi! I was using your script and until few days it worked perfectly.

    Now for testing whats wrong I opened your demo on my iphone4s and it works.

    Then after copying your original demo to my server it doesnt show up anymore. Do you have any clue where could the problem be?

    This is the link:

    1. Okay its working again (maybe some safari cache problem?)

      Thanks again on your script and here is the translation for Croatian language:

      hr_hr: 'Instaliraj ovu aplikaciju na svoj %device: klikni na %icon i odaberi Dodaj u početni zaslon.'

  201. Firstly id like to commend you on a great piece of code. Simple straight forward but still a great feature. However i have tried many times to implement this on my blog (tumblr) but with no success and i wanted to know if this was not possible to implement on my blog or if i was doing something wrong. I tried simply placing the code as well as inputting the code itself as javascript within my html and also tried manipulating it but with no success… Any help would be greatly appreciated.

    Thanks in advance.

  202. I am using this script in my jquerymobile app. I load all the pages in ajax and I need to show this balloon in specific url, lets say, but it shows when the page is loaded. how to prevent the balloon to load and show in specific url?

  203. Thanks for this! Your code is the best yet! I have a question regarding the configuration. Can I just change the settings in the add2home.js or do I need to follow your suggestion: “You can customize the script behaviors by setting the addToHomeConfig global variable *before* the add2home.js script is included into the page. Let me stress on this. The variable must be globally accessible and must be defined before the script is included inside the page.

    ALSO, is there a script for Android/Blackberry/other devices?

  204. I loved as much as you will receive carried out right here.
    The sketch is attractive, your authored subject matter stylish.
    nonetheless, you command get bought an nervousness over that you wish be delivering
    the following. unwell unquestionably come further formerly again since exactly the same nearly very often inside case you
    shield this increase.

  205. At first I thought the bottomOffset setting was not working. Then I realized the script was assuming that the address bar was present. I have hidden the address bar by auto-scrolling, and that was bringing the balloon up towards the middle of the screen.

    I have addressed this by using bottomOffset: -60. Do you have a better suggestion? I am only testing this on an older iPhone 4s, and I am wondering if this number will be incorrect on retina devices.

  206. I tested this on iOS4 and 5 working fine but on iOS 6 when we create shortcut to screen and try to browse that site it open a black page and it keep try loading it….why so?
    I am having internal site

  207. Question. On the iphone5 when you add to home screen all that is fine. When I tap to open what was added to home screen. The height of what is being viewed is not going the full height of the screen. Any fixes for this.

  208. If you have multiple “apps” on the same website (website/app1, website/app2) the localstorage in the browser is the same. So after being prompted on loading the first app the user will not be prompted on the 2nd app as it appears he is “returning” too soon. Maybe should clear time in localstorage if app is added to home screen.

    1. there’s no golden solution to detect if the website has been added to the homescreen. You should detect that yourself based on your app and clear the localstorage accordingly

      1. No I am still looking for a fix. Anyone at all know of a fix for height issue on the iPhone 5. Thanks.

  209. This script rocks.

    I just have a question could someone teach me how to track the button or how to track if someone has installed the icon to their homescreen?

    I want to see how many people open the “homescreen icon”.

    Thanks a lot!

  210. in iOS6 I tried add to home screen button to add my wbsite shortcut but when I open using that shorcut it opens white page and aloader that keep loading ….

    Earlier versions of iOS it works fine..please help

  211. Thank you for this amazing script.

    I’ve tested it on my site with my iphone 4s IOS5 but when I test it on my wife’s iPhone 4s which had just been updated to IOS6 it doesn’t show up.

    Any ideas why?

  212. Its a great script but on my ipad mini the bottomOffset does not work properly, it works more like a top offset. Also, is there a way that the x position can be set a percentage rather than a fixed value as the baloon does not line up in the middle of the page when I rorate the ipad.

  213. Is there a way to disable add2home from showing up on iPad. I’m looking to only have it appear on iPhone/iPod.

  214. Thanks again for this

    I’m testing this on my iPhone 4s IOS5… If I add my site to my homescreen in landscape view & then access it from the homescreen icon in portrait view, my site shows as if still in landscape i.e. zoomed in.

    Whilst this is not a big problem, my site is mobile-optimised with a fixed view and as such does not support zooming in & out.

    Do you know of any way to fix this?

    Will donate $10 for a working solution.


  215. Hi,

    Many thanks indeed for the great script. Can I ask if it is possible to not use current URL for saving to home screen and use the home page URL instead?

    We are an ecommerce store and if the prompt appears outside of the home page, for example on a product, well that page could be deleted once sold out, rendering the shortcut useless.



    Always Riding

  216. Somehow, the close button in the corner of the bubble has no effect. I am testing this on an iPhone 5 and iPad 3, both iOS 6.

    Also the position of the iPad bubble seems a bit off. The arrow does not point towards the “sharing” button.

  217. Hi Matteo,
    The qrcode does not work. I downloaded the examples, and they do not work. I’m iOS6 / iPhone 4s. Can you confirm that the script is still up?

  218. Matteo, the problem that I mentioned first and that has been confirmed by Web Design Boulder seems to be based on the iOS version. It does work on iOS 5, but does not work on iOS 6. Could you look into this?
    Thank you!

    1. I just tried it on 6.0.1 and (guess what) I can’t replicate the issue. If I click the X the popup closes correctly.

      It’s hard to debug if I can’t replicate the issue. Anyway, I’d put the close sensible area on the whole balloon. That should help.

  219. Is it possible to have returningvisitor do the opposite? So first time users see message, returning users do not see message?

  220. When I click the icon after adding it to the home screen it’s not opening the website inside the safari browser – not even in your demo. I don’t see any browser – just the page full screen. How can that be?

  221. Pop up says the app is called ‘settings’.
    Can we manually set the name of app for shortcut..

  222. This is awesome but it keeps showing up even though it’s already installed.

    Is there a fix for that? Please help.

  223. Is it possible to make this appear only for first time when a user come to your site.. So in other terms not to show the message to returning users?

  224. Hey great code! Thanks!

    Mine works, but when the bubble pops up, it is very very tiny. Only when I zoom in does it become larger and eventually the proper size. How can I fix this?

    Thanks so much!! Happy New Year!!

  225. Yeah man, I just did it, although I’m working out the kinks. What’s your host? You simply download the files (“Get The Script”), and upload the css and js files onto your host. It can be anywhere, like in some folder. Then add the above code to your header file, where you see other “<link"s and "rel"s. (header.php is located under wp-content, themes, your theme). Just add the two lines of code right below the other similar <link lines at or near the top. Then change the /path/to to match the path you uploaded the files to! And voila!

  226. The close button of the balloon doesn’t work in Safari’s private mode. Is there a work around for this problem? (iOS 6.0.1, iPad 4)

  227. Dear wordpress customers:

    from your ftp client (server)
    1. create a folder (ex. iphone)
    2. upload add2home.css and add2home.js in your folder
    3. go to appearance/editor
    4. search header.php and put the code

    and replace patch/to/ by your created folder.
    * if you have problems. put your complete url



    1. Ok, so I have a wordpress site. I went into my ftp and added a folder named iDevices into my wp-content folder. I then added your add2home.sss and add2home.js files into the folder. I then went to appearance/editor, header. php and entered the code:

      I then tried to open my website on iPad and iPhone, but there is absolutely no add to home screen button appearing. Is there another step that I’m missing?

  228. The script works pretty well on my HTML5 web app, except when I turn On the icon feature (I set the Config variable before the .js file, as instructed) it displays “null” instead of my icon. Any idea on what I did wrong or what the problem might be?

    Thanks a lot. It’s a wonderful script, by the way.

      1. Yes, I’m using the latest version, and have the icon normally referenced inside HEAD as:

        Still, I get a “null” message instead of the icon.

  229. there happened a Javascript error that “SECURITY_ERR:DOM Exception: An attempt was made to break through the security policy of the user agent”. I didn’t know what’s the matter, could you tell me why?

  230. Is there a way to make the “app” open up to a specific page?

    I want the app to always open on

    even if they saved the app from

    How can this be accomplished? Thanks in advance,


  231. Hey Matteo,

    Great plugin! The only problem i have is one which happens on just one iphone 4s. I have no idea why but on my other iphone 4s is does work.

    It’s the same problem multiple other have been experiencing with the close button. Mine simply does not close at all. Not even with the latest version where you made the whole bubble a close listener.

    I’m using Sencha Touch 2. Thanks!


  232. Is possible to check if the user added the shortcut on the home so not showing again the popup?

    And the last thing, if set expire= 60 it will show the popup again after 60 minutes right?

    Thank you

    1. Is possible to check if the user added the shortcut on the home so not showing again the popup?

      1. Hi Matteo, could you elaborate on the use of the window.localtion.href command to do this. I have WordPress sites and have placed the code in to the header.php file however I am getting the pop-up on every page and would like to just have it appear on the home screen or just appear the once when you visit the site no on every subsequent page clicked after landing. I tried adding the code however this does not appear to work in the WordPress environment. Thanks for you support and Awesome code! 🙂

  233. It seems like a great plugin except that I experience this strange behaviour.

    On my iphone or ipad it drops down and is only visible for like 50% of the opacity and then it dissapears again. I did use the example code from the download.
    Do you have any idea?

  234. hi, im jsut starting html and css.. but ive been using ipod touch for almost a year.. i found your tweak to be very useful… im fond of making html based shortcut for my apps / tools on my work.. ive got tons of tools, so i decided to create a html page and link all .exe files + my notes + spiel + email updates + notepad on a single page.. if its posible, you could make / teach me/us to create a shortcut for toggles on the settings app..

  235. Ok, so I have a wordpress site. I went into my ftp and added a folder named iDevices into my wp-content folder. I then added your add2home.sss and add2home.js files into the folder. I then went to appearance/editor, header. php and entered the code:
    I then tried to open my website on iPad and iPhone, but there is absolutely no add to home screen button appearing. Is there another step that I’m missing? Any help would be greatly appreciated!

  236. Thanks for the tutorial!!!
    Everything works great!
    So, you mentioned a different way of preventing the balloon from showing. I don’t have the “web app capability”, I include the script to the home page of my website. My problem is that I’m new in the matter and I don’t really know how to check for a special url hash. Could you please show me an example? or a different option?
    In advance,
    Thanks very much.

  237. Very nice but it seems like once I am using this if I add my web app to home screen and then open my web app from that home screen icon it no longer has the address bar in safari. Also in my page I added to homescreen I have redirects with rel=”external” and new instances of safari are then opened. Anyway to keep the default behavior when I added to home screen before using your plug in?

  238. Thank you so much for this script! I do have one problem though.. When I scan a QR code the link will not open directly in Safari, but inside the QR application – and then you don’t get this popup message..

    Is there a way to solve this?
    (I also tried scanning your QR code, but this is also opening inside the QR app, and there is no popup..)

  239. I had to change the event listener to touchstart – the click event did not work on my iphone or ipad to close the balloon.

    if ( options.closeButton ) balloon.addEventListener(‘touchstart’, clicked, false);

  240. Hello!

    This is an AWESOME article. Thanks!!!

    The only problem I have is that when I set touchIcon:true, it shows “null” in place of the icon.

    The head tag has

    Am I doing something wrong?

  241. I use Rapidweaver and have added the Standard Usage code to the head and the addtohome.css and add2home.js to my htdocs folder, but nothing happens, any idea what I am doing wrong?

  242. Hi,

    I miss something like a developer-Mode to test and style the bubble in desktop-browser. Something like Desktop=true as a parameter. Mayer there is a Otter solution i dont recognize!?

    Thanks for this Great Script.

    Gereinigt from Germany

  243. First of all as everybody else, I want to thank you and congratulate you for your great code.
    I added the meta code you provided above for “apple-mobile-web-app-capable” but it keeps showing the popup. Have you any suggestion ?

    Thanks a lot !

  244. Hi,

    This works great when I go directly to my mobile website URL. However when I visit my regular homepage URL and then is being forwarded to the mobile website url, then this script is not showing up.

    Any ideas?

  245. Thanks for the plugin!
    Is great, but I found that it doesn’t work when private browsing is on, I added this bit of code to bypass the sessionStorage part. It could explain why the last commenter’s 2 phones are different..
    function clicked () {
    var canstore = true;
    var testKey = ‘qeTest’, storage = window.sessionStorage;
    try {
    // Try and catch quota exceeded errors
    storage.setItem(testKey, ‘1’);
    } catch (error) {
    if (error.code === DOMException.QUOTA_EXCEEDED_ERR && storage.length === 0)
    //alert(‘Hello, private browser.’);
    canstore = true;
    else throw error;
    if (canstore = false){
    isSessionActive = true;
    sessionStorage.setItem(‘addToHomeSession’, ‘1’);

    That was taken from here:

    Thanks again

  246. Hi

    Do you have set instructions on how to add this or a tutorial? Is it suited for wordpress?

    Thank you

  247. After adding to home screen and then opening the status bar on the bottom is missing. Is there a possibility to publish this again?

  248. Hi , thank you for the great plugin.
    I had a small question:
    Can you somehow trace how many people added the app to their home screen?
    Track how many click throughout Google analitics or something?

    Thank you

  249. One more question:
    Opening the site from the installed home screen there is on iphone 5 devices free space at the top and the bottom. Is there a solution to show it over the whole screen?

  250. Very nice!! And working on the iPad but not on the iphone (4). Like many others I am not able to close the message box (tested it on the demo site, before installing on my own site)

    Can make a movie if you want to.

    For the rest; great work!

      1. Hi, the iphone is an iphone 4 with IOS 6.1 installed.

        The video of the iphone behaviour is on youtube:

        With an ipad I visited the same demo page and it works there:

        It’s the same some of the others are saying in previous comments. Doesn’t matter where you tab the message will not close. Doing this on the iPad it works like expected. If you need me to test anything just let me know.