This is a custom web component that renders a calculator for home electrification incentives. Users input some information about themselves, and the calculator shows incentives --- tax credits, rebates, etc. --- that they're eligible for.
The calculator can be embedded on third-party websites. An instance of it is available on Rewiring America's website.
In addition to the calculator itself, this repo contains a small website that demonstrates the component. It's hosted at https://embed.rewiringamerica.org.
To embed the calculator on your website:
-
Sign up for the Rewiring America API and get an API key.
-
Add the following to your page's
<head>tag:<script type="module" src="https://embed.rewiringamerica.org/state-calculator.js" ></script> <link rel="stylesheet" type="text/css" href="https://embed.rewiringamerica.org/rewiring-fonts.css" />
-
Add the following in the body of the page:
<rewiring-america-state-calculator api-key="YOUR_API_KEY"> </rewiring-america-state-calculator>
The calculator conforms to WCAG 2.1 level AA. Our latest self-assessment for WCAG compliance can be found in the /docs folder
The calculator component supports the following attributes to customize its behavior.
| Attribute | Type | Description | Default |
|---|---|---|---|
lang |
string | The language of user-visible text. en (English) and es (Spanish) are supported. Any other value will fall back to English. |
lang from nearest DOM ancestor, or en if none |
state |
2-letter string | Two-letter state code (e.g. RI, CO). If set, the calculator will show an error message if the user inputs a location outside that state. |
none |
zip |
5-digit string | A ZIP code to pre-populate in the form. | none |
owner-status |
string | A homeowner/renter status to pre-populate in the form. Valid values: homeowner, renter |
homeowner |
household-income |
number | A household income to pre-populate in the form. | 0 |
tax-filing |
string | A tax-filing status to pre-populate in the form. Valid values: single, joint, married_filing_separately, hoh |
single |
household-size |
number | A household size to pre-populate in the form. Valid values: 1 through 8 inclusive |
1 |
Values are pre-populated from attributes on page load, and when the user clicks "Reset calculator".
The calculator component dispatches custom events when the form is submitted and reset. These are intended to be used for analytics. When the event is dispatched, the form submission or reset has already happened, and you don't need to do anything.
The events' target is the calculator component. They are not cancelable. You can listen for them with addEventListener(), as follows:
<script>
// NB:- place *after* the <rewiring-america-state-calculator> tag to ensure it exists:
var calc = document.getElementsByTagName(
'rewiring-america-state-calculator',
)[0];
calc.addEventListener('calculator-submitted', function (event) {
// replace the following with a call to your event tracking system:
console.log(event.detail.formData);
});
</script>| Event name | detail |
|---|---|
calculator-submitted |
The key formData contains an object with the form data that was submitted. Possible keys are zip, owner_status, household_income, household_size, tax_filing, and projects. |
calculator-reset |
None |
The colors of some UI elements can be customized by overriding CSS variables.
Overriding values must be defined on the calculator element. The values must be a color in absolute or relative CSS rgb() syntax, and must not include an alpha value. For example:
rewiring-america-state-calculator {
/* Absolute value syntax */
--ra-color-background-button: 195 0 74;
/* Relative color syntax */
--ra-color-text-link: from blue r g b;
}| Variable name | Usage |
|---|---|
--ra-color-background-button |
The background color of the submit button in the calculator form. |
--ra-color-text-button |
The text color of the submit button in the calculator form. |
--ra-color-text-link |
The text color of links throughout the calculator UI. |
The calculator defines and uses many other CSS variables, but their existence and behavior are not guaranteed to be stable; override them at your own risk. Only variables prefixed with --ra- are supported customization points.
-
Get an API key for the Rewiring America incentives API by signing up here. (RA employees: ask internally.)
-
Put the API key in a file called
.env.localat the root of your working copy, as follows:REWIRING_AMERICA_API_KEY=zpka_********************************_******** -
Install Node 18. We recommend using NVM.
-
Install Yarn by running
corepack enable. -
Run
yarn installto install dependencies. -
Run
yarn serve:widgetto run a local server that serves the embed demo website. Access it athttp://localhost:1234.
-
Run
yarn build:widgetto build a single.jsfile containing the calculator and all of its transitive dependencies. -
The bundled file is written to
dist/state-calculator.js. This file anddist/rewiring-fonts.cssare all that's needed to embed the calculator on any webpage.
This codebase doesn't have a significant roadmap of its own. Changes here are primarily driven by the needs of our broader incentives API / calculator project. As the API expands to incentives with more complex structures, this frontend will evolve to match.
There are a few tasks specific to this codebase that we're interested in:
-
Automatically generating
src/api/calculator-types-v1.tsfrom the API spec, rather than manually maintaining it. -
Better test coverage, including tests that mock out API responses.
This codebase actually contains two calculator frontends: one centered in src/calculator.ts and one centered in src/state-calculator.ts. The former is soon to be deprecated and should not be used anymore. It only has support for federal incentives from the Inflation Reduction Act. The latter has support for incentives from states and utilities, and is where all new development is happening.
If you find an inaccuracy in incentive information, please see our incentive API repo for what to do.
If you find a visual, behavioral, or accessibility bug in the new calculator frontend (that is, the one that looks like this), please file an issue in this repo. (The old frontend is soon to be deprecated, so there's no need to file issues for it.)
If you have a feature request for the new frontend, please file it as an issue. We can't make promises of when or if we'll get to it, but we are interested to hear what people want from this project.
We aren't ruling out accepting external code contributions, but we'd like to discuss it before you put too much work into a PR. The best place to have that discussion is in an issue on this repo, but you can also email us at [email protected].
See CONTRIBUTING.md for a guide to the codebase.