Placeholders.js

Placeholders.js is a JavaScript polyfill for the HTML5 placeholder attribute. It's lightweight, has zero dependencies and works in pretty much any browser you can imagine.

Want to help out? Contribute on GitHub.

Examples

Features

Placeholders.js works on both input and textarea elements. It only requires a single line of HTML. It does its best to simulate native styles, and exposes a class name so you can style the placeholder as you choose.

It works for elements added to the page by JavaScript, and also for placeholder attributes that are changed by a script sometime after page load, and it makes sure that placeholder text isn't submitted as form data - a common issue with other placeholder solutions.

It works in a massive range of browsers, including Internet Explorer 6, and it does it without any dependencies, so there's no need to include jQuery if you don't want to! What's more, it manages to do all this in just 4kB of JavaScript.


Adapters

Placeholders.js is available as a basic standalone script or alternatively bundled with a DOM library adapter. If you're using one of the DOM libraries listed below it is recommended that you use a version of Placeholders.js bundled with the appropriate adapter.

The adapters patch methods of DOM libraries so you don't end up with the placeholder text as the return value of, for example, the jQuery .val() method.

Available adapters

Library Description Downloads
jQuery Patches the .val() method to return the empty string when the element in question has an active placeholder placeholders.jquery.min.js (v3.0.2 minified, 4kb)
placeholders.jquery.js (v3.0.2 unminified, 18kb)
Prototype Patches the .getValue() method (instance and static), as well as the $F utility function to return the empty string when the element in question has an active placeholder. placeholders.prototype.min.js (v3.0.2 minified, 4kb)
placeholders.prototype.js (v3.0.2 unminified, 19kb)
YUI3 Patches the .get() method of the Node module to return the empty string when the element in question has an active placeholder. You must require the placeholders module in your app for this to work. placeholders.yui3.min.js (v3.0.2 minified, 4kb)
placeholders.yui3.js (v3.0.2 unminified, 19kb)

Setup

Placeholders.js is incredibly easy to use. Just download the script, include it at the bottom of any web page and let it do the rest. It's just one extra line in your markup. Browsers that support the placeholder attribute natively will be unaffected and work as usual.

If you want a bit more control over how the polyfill behaves, you can configure it with HTML5 data-* attributes on the root <html> element.

Options

Option Description
data-placeholder-focus Set this to false if you want your placeholders to hide when a user enters something in the field, instead of just giving focus to the field. This is how later versions of Chrome and Safari behave natively.
data-placeholder-live Set this to false if you don't want your placeholders to update if you change them via JavaScript, or add new elements to the page after it's loaded. If you know you won't be changing the page in this way, you should always set this to false.

Is there an option that you think would be useful? Just open an issue on GitHub and we'll look into adding it. Alternatively, fork the project and add it yourself!


API

Placeholders.js exposes a very simple API that you can use to handle your placeholders via JavaScript. The main use of these methods is so you can show the placeholders again in situations the polyfill can't handle on its own, such as cancelled form submissions.

Method Description
Placeholders.disable( [element] ) Call this method to hide the placeholder on an element, or on all descendants of an element. If you don't pass in an element, all placeholders will be affected.
Placeholders.enable( [element] ) Call this method to show the placeholder on an element, or on all descendants of an element. If you don't pass in an element, all placeholders will be affected.

Contributing

Placeholders.js is open-source and we welcome all contributions, suggestions and ideas. If you decide to help out by submitting a pull request, just follow these simple instructions to get your development environment up and running.

  1. Make sure you have Node.js and its package manager, npm, installed
  2. Install Grunt (minimum version 0.4) globally: npm install -g grunt-cli
  3. Fork Placeholders.js to your own GitHub account
  4. Clone your fork of the repository: git clone git@github.com:username/Placeholders.js
  5. Navigate to the clone directory and install development dependencies: npm install
  6. Be sure to run Grunt before committing any changes: grunt

Thanks

Placeholders.js was originally developed, and is maintained by, James Allardice. Huge thanks to the following people for their help in this project.