Web Standard: JavaScript
Note
All EPA public content pages and web applications are required to follow this standard. Intranet and Microsoft 365 do not allow for JavaScript. Your web application may also not allow for JavaScript.
Modern JavaScript is a powerful language. We can do so much with it these days, from simple content and UI updates to 2D/3D games. Its capabilities often cause developers to forget that you still need to ensure that your pages and scripts are accessible, conform to EPA and Federal Web Standards, and are not reliant upon third-party scripts.
We provide a standard suite of JS files for everyone at the Agency to use. Linking to the EPA master JS files will improve your site performance, as users may cache a copy of the files.
Web area webmasters in the WebCMS can write JS, per page, as needed. All JS, in content managed by the WebCMS, is output at the bottom of the HTML, just before the closing </body>
tag. Placing scripts here speeds up epa.gov for our readers, but placing too many scripts or lines of code will slow down pages for content editors.
Definitions
JavaScript (JS) is a client-side scripting language. You can use it to validate forms, detect user actions (such as individual keystrokes), or retrieve data from a server without interfering with the display or behavior of the open web page. JavaScript can also power entire applications, like Gmail.
Accessibility: It is a misconception those with disabilities don't have or 'do' JavaScript, and thus, it's acceptable to have inaccessible scripted interfaces, so long as it is accessible with JavaScript disabled. This is false: a 2019 survey by WebAIM of screen reader users found that 99.3% of respondents had JavaScript enabled. Accessibility guidelines require scripted interfaces to be accessible. WCAG 2.0 and all other modern guidelines allow you to require JavaScript, but the scripted content and interactions must be compliant with the guidelines.
Content Requirements
- All content generated with JavaScript must follow all EPA and Federal Web requirements.
- All pages using JavaScript must be accessible.
- Do not use JS to create or modify styles for EPA content. EPA has a standard look and feel.
- Do not use too much JavaScript.
- Sometimes you'll see a website where everything has been done with JS: the HTML and CSS have been generated by JS, which can present accessibility and other issues.
- It's also slow, both for the developer and for your readers.
- If you find that loading all of your script code into the WebCMS Page JavaScript field slows down your editing experience, move the code into a separate file and work with WebCMS Support to upload that file to the file server.
- Do not rely on or link to JavaScript files not hosted on epa.gov. We have no control over the contents of third-party websites.
- Third-party websites do not include other EPA sites.
- Work with WebCMS Support to upload copies of those files to the file server.
- In the WebCMS, all JS must go into the Page JavaScript field; JS in any other field will be stripped out.
- JS for your standalone application can go anywhere in the HTML; we recommend you output it at the bottom of the page or that you defer its loading.
- Web pages should not be dependent on JavaScript to work.
- Functions should first check to see if an object is available. If not, then fail silently.
- HTML and JavaScript are separated: no inline event handlers.
- With JavaScript off, nothing happens;
<noscript>
should not be necessary. - If you offer advanced functionality and your pages cannot work the same way without JS:
- Ensure that you account for users without JavaScript.
- While this does not necessarily mean that all functionality must work without scripting (though this would be optimal), if it does not work without scripting, you must avoid a confusing or non-functional presentation that may appear to function, but does not because of lack of JavaScript support.
- At a minimum, provide text equivalents or a phone number or email address to get help.
- Ensure that you account for users without JavaScript.
About this Standard
All EPA public web content must adhere to all federal requirements including; the EPA Web Standards, the U.S. Web Design System guidelines, federal plain language guidelines, and the 21st Century Integrated Digital Experience Act. Internal content, including Intranet and Microsoft 365, may differ from the public content. If not explicitly stated, content must adhere to all federal requirements.
Original effective date September 28, 2005
Last approved on: 04/12/2023
Web Council review by: 04/12/2026 (or earlier if deemed necessary by the Web Council)