{"id":21619050,"url":"https://github.com/usds/html-prototype","last_synced_at":"2025-03-18T18:19:53.398Z","repository":{"id":35413111,"uuid":"214522401","full_name":"usds/html-prototype","owner":"usds","description":"Framework with USWDS 2 and static prototyping","archived":false,"fork":false,"pushed_at":"2022-12-04T15:38:52.000Z","size":7740,"stargazers_count":6,"open_issues_count":14,"forks_count":4,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-01-24T21:28:37.691Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"SCSS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/usds.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-10-11T20:20:53.000Z","updated_at":"2022-02-22T19:53:36.000Z","dependencies_parsed_at":"2022-08-27T17:20:14.577Z","dependency_job_id":null,"html_url":"https://github.com/usds/html-prototype","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usds%2Fhtml-prototype","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usds%2Fhtml-prototype/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usds%2Fhtml-prototype/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usds%2Fhtml-prototype/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/usds","download_url":"https://codeload.github.com/usds/html-prototype/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244277179,"owners_count":20427312,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-24T23:07:45.415Z","updated_at":"2025-03-18T18:19:53.369Z","avatar_url":"https://github.com/usds.png","language":"SCSS","funding_links":[],"categories":[],"sub_categories":[],"readme":"## To run\n\n```\n$ npm install\n$ bundle exec jekyll serve\n```\n\n### Updating USWDS to a later version.\n\nThere are a couple ways to update the USWDS:\n\n#### Change theme settings\n\nThis site uses custom USWDS theme settings in `./assets/uswds-theme`. Use this if you want to include or remove utilities or update utility settings.\n\n1. Compile usds.css `gulp uswds-build-sass`\n2. Run jekyll `bundle exec jekyll serve`\n\n\n#### Only update the USDS.css without getting new functions and tokens for use in usds.gov project files\n\nUse this to patch any display bugs through updates to USWDS.\n\n1. Install the package `npm install --save-dev *new-USWDS-version-number*`\n2. Compile usds.css `gulp uswds-build-sass`\n3. Run jekyll `bundle exec jekyll serve`\n\n#### Update USDS and get new functions and tokens for use in usds.gov project files\n\nThis will will update some of the scss files in `./assets/uswds-sass`, but will not overwrite any of your files in `./assets/uswds-theme`.\n\n1. Install the package `npm install --save-dev *new-USWDS-version-number*`\n2. Run `gulp update`\n3. Compile usds.css `gulp uswds-build-sass`\n4. Run Jekyll `bundle exec jekyll serve`\n\n## How the prototype scripting works\n\nWhen submitting the form, data will be pushed to session storage and pulled back immediate so that based on answers, you can link to different pages or perform other kinds of actions.\n\nTo do this, you'll need to have this snippet at the bottom of each page:\n\n```html\n\u003cscript\u003e\n  $(document).ready(function() {\n    $('form').on('submit', function() {\n      if (!checkValidityIfSupported($('form').get(0))) {\n        return false;\n      }\n      else {\n        nextPage(\"next-page.html\");\n        return false;\n      }\n    });\n  });\n\u003c/script\u003e\n```\n\nWhen we run `updateStoredData()`, we are taking the `value` entered in any type of input and placing that in the session storage as a key/value pair. The **key** is saved as a variable. So lets you want to drive people named \"Bob\" to one page and everyone else to another page. You would need to have this input in your form:\n\n```html\n\u003cinput id=\"first_name\" name=\"first_name\" type=\"text\" \u003e\n```\n\nThen in the `\u003cscript\u003e` at the bottom you can do:\n```html\n\u003cscript\u003e\n  $(document).ready(function() {\n    $('form').on('submit', function() {\n      if (!checkValidityIfSupported($('form').get(0))) {\n        return false;\n      }\n      else {\n        updateStoredData();\n\n        if (first_name == \"Bob\") {\n          nextPage(\"bob.html\");\n        }\n        else {\n          nextPage(\"others.html\");\n        }\n        return false;\n      }\n    });\n  });\n\u003c/script\u003e\n```\n\n\n\n## Follow-up questions\nIn some forms, you may want to ask an inline follow-up if a user selects a specific answer. This is enabled on radios, select boxes, and checkboxes using a mix of `data` attributes and `id` attributes.\n\nOn the form element that triggers a follow-up, use the `data-followup` attribute with a value that corresponds to the `id` of element you wish toggle on and off. The follow-up can appear in any part of the DOM and can include any type of content. For accessibility, also use `aria-controls` and `aria-expanded` attributes.\n\n```html\n\u003cinput id=\"other\" type=\"radio\" name=\"historical_figure\" value=\"Other\" data-followup=\"historical-figure-followup\" data-controls=\"historical-figure-followup\" aria-expanded=\"false\" required\u003e\n\u003clabel for=\"other\"\u003eOther\u003c/label\u003e\n\u003cdiv id=\"historical-figure-followup\" hidden\u003e\n    \u003clabel for=\"other-hero\"\u003eSpecify\u003c/label\u003e\n    \u003cinput type=\"text\" id=\"other-hero\" disabled\u003e\n\u003c/div\u003e\n```\n\n### Select Boxes\nFor Select boxes, put the `data-followup` on the `\u003coption\u003e`.\n\n```html\n\u003clabel for=\"additional_field\"\u003eAdditional Field?\u003c/label\u003e\n\u003cselect name=\"additional_field\" id=\"additional_field\"\u003e\n  \u003coption value=\"\"\u003e\u003c/option\u003e\n  \u003coption value=\"no\"\u003eNo\u003c/option\u003e\n  \u003coption value=\"yes\" data-followup=\"additional_field_q\"\u003eYes\u003c/option\u003e\n\u003c/select\u003e\n\u003cdiv id=\"additional_field_q\" hidden aria-hidden=\"true\"\u003e\n    \u003clabel for=\"g\"\u003eWhat is it?\u003c/label\u003e\n    \u003cinput type=\"text\" id=\"g\" \u003e\n\u003c/div\u003e\n```\n\n\n\n## Printing Form Data\n\nForm data can be printed in either inputs or HTML elements using the `data-print` attribute. The value of that attribute should equal the ID of the corresponding input. So, if we wanted to greet Bob on his page, we would write:\n\n```html\n\u003cp\u003eWelcome to your very own page, \u003cspan data-print=\"first_name\"\u003e\u003c/span\u003e\u003cp\u003e\n```\n\nIf you were persisting data in a form, you can add the `data-print` attribute to an input. The ID doesn't have to match:\n\n```html\n\u003cinput id=\"first_name\" name=\"first_name\" type=\"text\" data-print=\"first_name\"\u003e\n```\n\n\n## URL Parameters\nAny page loaded with a URL parameter or parameters will be stored as key/value pairs in `sessionStorage`. For example, when you visit a page as `http://site.com?foo=bar`, your sessionStorage will be updated with `foo: \"bar\"` to use later.\n\n## Filtering Content on the page\nFiltering content will allow you to handle multiple states on a single page. For example, let's say you have a page that would show some content that is conditional upon some stored data. You can use the data attribute `data-filter-[STORED_ID]=\"[STORED_ID_VALUE]\"` to keep it on the page. If the `STORED_ID_VALUE` attribute does not match what is in your session data, the element will be removed from the DOM.\n\nIf filtering content, **use underscores as separators, note hyphens**\n\n```html\n// Session Data { foo: \"bar\" }\n\n\u003cdiv data-filter-foo=\"bar\"\u003e     // Element stays on page\n\u003cdiv data-filter-foo=\"baz\"\u003e     // Element is removed\n\u003cdiv data-filter-foo=\"bar baz\"\u003e // Element stays on page\n```\n\n\n## Using Jekyll includes for the form fields\n\nAll form fields in the prototype are handled by Jekyll includes. Here are includes for the following types of input includes and the parameters they accept.\n\nAll form fields are required by default unless the optional parameter is passed into the include.\n\n### Text (with a param, could be modified to be any basic text input)\n\nIf fields are not indicated as required, they do not need to be included.\n\n```html\n{% include form-fields/_text-field.html\n  id=\"first_name\"                            \n  label_text=\"Form label\"                    \n%}\n```\n\n#### Required parameters\n\n- `id=\"foo_bar\"`: Needs to use underscores. Maps to `name` and `id` attributes.\n- `label_text=\"Foo bar\"`: This is the label text.\n\n#### Optional Parameters\n\n- `label_classes=\"class1 class2\"`: Adds class names to the label. Can use one or multiple.\n- `optional=\"true\"`: Only accepts \"true\", makes form field optional instead of required by removing the `required` attribute. Also adds \"(Optional)\" next to the label text.\n- `hint=\"This is some hint text\"`: Hint text under the label\n- `type=\"email\"`: Can be any HTML5 input type (sample displays email). By default, inputs are `type=\"text\"`.\n- `input_classes=\"class1 class2\"`: Adds class names to the input. Can use one or multiple.\n- `prepopulate=\"session_storage_id\"`: Pre-populates the form field with data from any `sessionStorage` key, which would usually be the `id` of another field.\n- `tel_keyboard=\"true\"`: Only accepts \"true\". Uses big numeric telephone keyboard on mobile devices.\n- `disabled=\"true\"`: Only accepts true. Disables a field. Use mainly when include is inside a followup.\n- `input_value=\"Custom input value\"`: Loads input with custom `value` for the input.\n\n### Textarea\n\nIf fields are not indicated as required, they do not need to be included.\n\n```html\n{% include form-fields/_text-area.html\n  id=\"first_name\"\n  label_text=\"Form label\"\n%}\n```\n\n#### Required parameters\n- `id=\"foo_bar\"`: Needs to use underscores. Maps to `name` and `id` attributes.\n- `label_text=\"Foo bar\"`: This is the label text.\n\n#### Optional Parameters\n- `label_classes=\"class1 class2\"`: Adds class names to the label. Can use one or multiple.\n- `optional=\"true\"`: Only accepts \"true\", makes form field optional instead of required by removing the `required` attribute. Also adds \"(Optional)\" next to the label text.\n- `hint=\"This is some hint text\"`: Hint text under the label\n- `input_classes=\"class1 class2\"`: Adds class names to the input. Can use one or multiple.\n- `prepopulate=\"session_storage_id\"`: Pre-populates the form field with data from any `sessionStorage` key, which would usually be the `id` of another field.\n- `disabled=\"true\"`: Only accepts true. Disables a field. Use mainly when include is inside a followup.\n\n### Checkbox\n\n```html\n{% include form-fields/_text-field.html\n  name=\"checkbox_group\"                      \n  id=\"checkbox_1\"\n  label_text=\"This is checkbox 1\"\n%}\n```\n\n#### Required parameters\n- `name=\"checkbox_group\"`: Maps to name attribute that all checkboxes in a set share\n- `id=\"foo_bar\"`: Needs to use underscores. Maps to `name` and `id` attributes.\n- `label_text=\"Foo bar\"`: This sets the label text and `value` property of the input.\n\n#### Optional Parameters\n- `label_classes=\"class1 class2\"`: Adds class names to the label. Can use one or multiple.\n- `input_classes=\"class1 class2\"`: Adds class names to the input. Can use one or multiple.\n- `checked=\"true\"`: Only accepts \"true\". Loads page with checkbox checked.\n- `prepopulate=\"session_storage_id\"`: Sets the checkedbox as `checked` if the sessionStorage key matches the value of the input.\n- `input_value=\"Custom input value\"`: Overrides the `label_text` with a custom `value` for the input.\n- `follow_up=\"followup_id\"`: Must be `id` of a `\u003cdiv\u003e` that includes followup fields or text. See more about [follow up questions](https://github.com/usds/html-prototype#follow-up-questions)\n- `disabled=\"true\"`: Only accepts true. Disables a field. Use mainly when include is inside a followup.\n\n### Radio\n\n```html\n{% include form-fields/_radio.html\n  name=\"radio_group\"\n  id=\"radio_1\"\n  label_text=\"This is radio 1\"\n%}\n```\n\n#### Required parameters\n- `name=\"radio_group\"`: Maps to name attribute that all radio options in a set share\n- `id=\"foo_bar\"`: Needs to use underscores. Maps to `name` and `id` attributes.\n- `label_text=\"Foo bar\"`: This sets the label text and `value` property of the input.\n\n#### Optional Parameters\n- `label_classes=\"class1 class2\"`: Adds class names to the label. Can use one or multiple.\n- `input_classes=\"class1 class2\"`: Adds class names to the input. Can use one or multiple.\n- `checked=\"true\"`: Only accepts \"true\". Loads page with radio selected.\n- `prepopulate=\"session_storage_id\"`: Sets the radio as `checked` if the sessionStorage key matches the value of the input.\n- `input_value=\"Custom input value\"`: Overrides the `label_text` with a custom `value` for the input.\n- `follow_up=\"followup_id\"`: Must be `id` of a `\u003cdiv\u003e` that includes followup fields or text. See more about [follow up questions](https://github.com/usds/html-prototype#follow-up-questions)\n- `disabled=\"true\"`: Only accepts true. Disables a field. Use mainly when include is inside a followup.\n- `optional=\"true\"`: Only accepts \"true\", makes radio selection optional instead of required by removing the `required` attribute.\n\n### Select box\n\n```html\n{% include form-fields/_select.html\n  id=\"title\"\n  label_text=\"Title\"\n  options=\" | Mr. | Mrs. | Ms. | Dr. | Other (Please specify)\"\n%}\n```\n\n#### Required parameters\n\n- `id=\"foo_bar\"`: Needs to use underscores. Maps to `name` and `id` attributes.\n- `label_text=\"Foo bar\"`: This is the label text.\n- `options=\"Option 1 | Option 2\"`: Options are separated by ` | `.\n\n#### Optional Parameters\n\n- `label_classes=\"class1 class2\"`: Adds class names to the label. Can use one or multiple.\n- `optional=\"true\"`: Only accepts \"true\", makes form field optional instead of required by removing the `required` attribute. Also adds \"(Optional)\" next to the label text.\n- `hint=\"This is some hint text\"`: Hint text under the label\n- `input_classes=\"class1 class2\"`: Adds class names to the input. Can use one or multiple.\n- `prepopulate=\"session_storage_id\"`: Pre-populates the form field with data from any `sessionStorage` key, which would usually be the `id` of another field.\n- `disabled=\"true\"`: Only accepts true. Disables a field. Use mainly when include is inside a followup.\n- `follow_up=\"followup_id\"`: Must be `id` of a `\u003cdiv\u003e` that includes followup fields or text. See more about [follow up questions](https://github.com/usds/html-prototype#follow-up-questions)\n- `follow_up_optional=\"true\"`: Only accepts true. Makes the followup question optional.\n- `follow_up_option=\"Option 2\"`: Indicates which option will generate the follow up question. Only allowed per select box. Must match one of the `options`.\n\n### Date\n\nBy default, dates are MM/DD/YYYY, which are entered in three separate fields.\n\n```html\n{% include form-fields/_date.html\n  id=\"todays_date\"\n%}\n```\n\n#### Required parameters\n- `id=\"some_date\"`: Needs to use underscores. Maps to name and id. The include will add `_month`, `_day`, and `_year` to the `name` and `id`.\n\n#### Optional Parameters\n- `label_text=\"Enter date\"`: Changes the text in the legend element. The default legend text id Date of Birth\n- `hide=\"day\"`: To exclude other fields. Accepts \"day\", \"month, \"year\" or a combination such as \"day month\". Include can be updated for other fields.\n-  `prepopulate=\"session_storage_id\"`: Used to add value of another key in session storage. Do not include `_month`, `_day`, and `_year` from the sessionStorage key.\n- `min_year=\"YYYY\"`: Min year for validation. Example: \"1900\"\n- `max_year`: Max year for validation. Example: \"2019\"\n- `optional=\"true\"`: Only accepts \"true\", makes form field optional instead of required\n- `disabled=\"true\"`: Only accepts true. Disables all fields. Use mainly when include is inside a followup.\n\n### List of states\n\nSelect box with all US states\n\n```html\n{% include form-fields/_state-select.html\n  id=\"some_state\"\n%}\n```\n\n#### Required parameters\n- `id=\"some_state\"`: Needs to use underscores. Maps to `name` and `id` attributes\n\n#### Optional Parameters\n- `label_text=\"Form label\"`: This is the label text. Otherwise will be \"State\"\n- `label_classes=\"class1 class2\"`: Adds class names to the label. Can use one or multiple.\n- `optional=\"true\"`: Only accepts \"true\", makes form field optional instead of required by removing the `required` attribute. Also adds \"(Optional)\" next to the label text.\n- `input_classes=\"class1 class2\"`: Adds class names to the input. Can use one or multiple.\n- `prepopulate=\"session_storage_id\"`: Pre-selects an option with data from a `sessionStorage` key, which would usually be the `id` of another field.\n- `disabled=\"true\"`: Only accepts true. Disables a field. Use mainly when include is inside a followup.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fusds%2Fhtml-prototype","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fusds%2Fhtml-prototype","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fusds%2Fhtml-prototype/lists"}