{"id":14990206,"url":"https://github.com/nathansmith/cta-modal","last_synced_at":"2025-04-12T02:06:00.720Z","repository":{"id":40364503,"uuid":"453452228","full_name":"nathansmith/cta-modal","owner":"nathansmith","description":"Call to action modal, as a Web Component","archived":false,"fork":false,"pushed_at":"2023-03-23T21:04:54.000Z","size":520,"stargazers_count":56,"open_issues_count":0,"forks_count":8,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-12T02:05:53.563Z","etag":null,"topics":["a11y","accessibility","aria-modal","modal","webcomponent","webcomponents"],"latest_commit_sha":null,"homepage":"https://host.sonspring.com/cta-modal","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nathansmith.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-01-29T16:28:03.000Z","updated_at":"2024-12-05T00:22:57.000Z","dependencies_parsed_at":"2024-09-24T16:00:50.746Z","dependency_job_id":null,"html_url":"https://github.com/nathansmith/cta-modal","commit_stats":{"total_commits":166,"total_committers":2,"mean_commits":83.0,"dds":"0.0060240963855421326","last_synced_commit":"8e887b23bbd70b13510ed5b32eb11a8551f7eb08"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nathansmith%2Fcta-modal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nathansmith%2Fcta-modal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nathansmith%2Fcta-modal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nathansmith%2Fcta-modal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nathansmith","download_url":"https://codeload.github.com/nathansmith/cta-modal/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248505862,"owners_count":21115354,"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":["a11y","accessibility","aria-modal","modal","webcomponent","webcomponents"],"created_at":"2024-09-24T14:19:42.452Z","updated_at":"2025-04-12T02:06:00.700Z","avatar_url":"https://github.com/nathansmith.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CTA Modal 🦒\n\nCTA Modal is a self-contained call to action [ARIA modal](https://www.w3.org/TR/wai-aria-practices/examples/dialog-modal/dialog.html), built as a [Web Component](https://developer.mozilla.org/en-US/docs/Web/Web_Components). It has zero runtime dependencies beyond a single JavaScript file, and only requires authoring HTML to use.\n\n- To see it in action, check out the [demo page](https://host.sonspring.com/cta-modal/).\n\n- All the TypeScript code is well tested, with 💯 [coverage](https://host.sonspring.com/cta-modal/coverage/cta-modal.ts.html).\n\n- The compiled [cta-modal.js](https://host.sonspring.com/cta-modal/dist/cta-modal.js) file is less than **8** kilobytes.\n\n- You can view the source code on [GitHub](https://github.com/nathansmith/cta-modal).\n\n- This [article](https://www.smashingmagazine.com/2022/04/cta-modal-build-web-component/) explains how it was built.\n\n---\n\n## How to use: install\n\nIf you are using [Node](https://nodejs.org/en/) with [NPM](https://www.npmjs.com/) (or [Yarn](https://yarnpkg.com/)) the install would look something like this.\n\n```bash\n# NPM.\nnpm install cta-modal\n```\n\n```bash\n# Yarn.\nyarn add cta-modal\n```\n\nThen simply import it into your own `*.js` or `*.ts` file.\n\n```javascript\n// Node.\nrequire('cta-modal');\n```\n\n```javascript\n// ES6.\nimport 'cta-modal';\n```\n\n---\n\n## How to use: flat file\n\nIf you are building a site where you want to include CTA Modal directly, then download the [cta-modal.js](https://host.sonspring.com/cta-modal/dist/cta-modal.js) file and reference it within your own `*.html` file.\n\n```html\n\u003chead\u003e\n  \u003cscript src=\"/path/to/cta-modal.js\"\u003e\u003c/script\u003e\n\u003c/head\u003e\n```\n\n**Note:** Alternatively, you can put the `script` at the end of your page, before the closing `\u003c/body\u003e` tag.\n\nBut you may see a flash of unstyled content, before the JS is parsed and attaches to the `\u003ccta-modal\u003e` tag. Placing it in the `\u003chead\u003e` ensures that the JS is parsed _ahead_ of time (no pun intended).\n\n---\n\n## How to use: basics\n\nAfter ensuring the JS is loaded in your code, all you need to do is type HTML like so.\n\nThe rest of the details are abstracted away. Additional accessibility hooks are added automatically.\n\n\u003c!-- prettier-ignore --\u003e\n```html\n\u003ccta-modal\u003e\n\n  \u003cdiv slot=\"button\"\u003e\n    \u003cp\u003e\n      \u003cbutton\n        class=\"cta-modal-toggle\"\n        type=\"button\"\n      \u003eOpen modal\u003c/button\u003e\n    \u003c/p\u003e\n  \u003c/div\u003e\n\n  \u003cdiv slot=\"modal\"\u003e\n    \u003ch2\u003eModal title\u003c/h2\u003e\n    \u003cp\u003eModal content\u003c/p\u003e\n    \u003cp\u003e\n      \u003cbutton\n        class=\"cta-modal-toggle\"\n        type=\"button\"\n      \u003eClose modal\u003c/button\u003e\n    \u003c/p\u003e\n  \u003c/div\u003e\n\n\u003c/cta-modal\u003e\n```\n\n**Note:** The inner tags with `slot` attributes yield specific functionality. Beyond that, any markup you want can go inside each of them.\n\n- `\u003cdiv slot=\"button\"\u003e` is **optional**.\n\n  It contains anything you want shown in the _page_ (not in the _modal_).\n\n- `\u003cdiv slot=\"modal\"\u003e` is **required**.\n\n  It contains anything you want shown in the _modal_ (not in the _page_).\n\nIf you do not include a `slot=\"button\"` element, then you will need to manually control setting the `\u003ccta-modal active=\"true\"\u003e` attribute yourself.\n\n---\n\n## How to use: extras\n\nThere are a few optional attributes that can be set on the `\u003ccta-modal\u003e` tag.\n\n\u003c!-- prettier-ignore --\u003e\n```html\n\u003ccta-modal\n  active=\"true\"\n\n  animated=\"false\"\n\n  close=\"Get outta here!\"\n\n  static=\"true\"\n\u003e\n  \u003c!-- etc. --\u003e\n\u003c/cta-modal\u003e\n```\n\n- `active=\"true\"` — Implicitly `false` by default.\n\n  You can use this to force a modal to display, without a user clicking anything.\n\n  I suggest using this sparingly, because we all know that unexpected modals can be annoying.\n\n- `animated=\"false\"` — Implicitly `true` by default.\n\n  This will cause the modal to hide/show immediately, without a fade animation.\n\n  If a user has their operating system's preference set for `prefers-reduced-motion` the animation will be disabled regardless of the flag.\n\n- `close=\"TEXT HERE\"` — Implicitly `\"Close\"` by default.\n\n  You can use this attribute to localize the text string shown in the close button's `title=\"Close\"` tooltip.\n\n  Whatever you put here will be shown on mouse hover, and will be read aloud to [screen readers](https://en.wikipedia.org/wiki/Screen_reader).\n\n- `static=\"true\"` — Implicitly `false` by default.\n\n  This will prevent clicks on the page overlay from triggering a modal close.\n\n  Additionally, the `escape` key will be ignored. Whereas, normally that key would also dismiss the modal.\n\n---\n\n## How to use: styling\n\nIf you want to override the default styles of the modal, that needs to be done via CSS variables. The reason for this is Web Components use the [shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM) which does not inherit styles from the parent page.\n\nThe following variables have been set to their default values. Feel free to tweak them to your liking.\n\n```css\ncta-modal {\n  /* Modal overlay. */\n  --cta-modal-overlay-background-color: rgba(0, 0, 0, 0.5);\n  --cta-modal-overlay-padding-top: 20px;\n  --cta-modal-overlay-padding-left: 20px;\n  --cta-modal-overlay-padding-right: 20px;\n  --cta-modal-overlay-padding-bottom: 20px;\n  --cta-modal-overlay-z-index: 100000;\n\n  /* Modal window. */\n  --cta-modal-dialog-background-color: #fff;\n  --cta-modal-dialog-border-radius: 5px;\n  --cta-modal-dialog-box-shadow: 0 2px 5px 0 rgba(0, 0, 0, 0.5);\n  --cta-modal-dialog-padding-top: 20px;\n  --cta-modal-dialog-padding-left: 20px;\n  --cta-modal-dialog-padding-right: 20px;\n  --cta-modal-dialog-padding-bottom: 20px;\n  --cta-modal-dialog-width: 500px;\n\n  /* Modal close button. */\n  --cta-modal-close-color: #fff;\n  --cta-modal-close-background-color: #000;\n  --cta-modal-close-border-radius: 50%;\n  --cta-modal-close-box-shadow: 0 0 0 1px #fff;\n  --cta-modal-close-display: block;\n  --cta-modal-close-font-family: 'Arial', sans-serif;\n  --cta-modal-close-font-size: 23px;\n  --cta-modal-close-line-height: 26px;\n  --cta-modal-close-width: 26px;\n\n  /* Modal close button - hover. */\n  --cta-modal-close-color-hover: #000;\n  --cta-modal-close-background-color-hover: #fff;\n  --cta-modal-close-box-shadow-hover: 0 0 0 1px #000;\n}\n```\n\n### Styling content\n\nIf you want to target content that is displayed within a modal, you can use a descendant selector scoped to the context of the `cta-modal` tag.\n\nFor instance: Let's say you want to make all content within the `slot=\"button\"` area blue, and wanted to make all the content within the `slot=\"modal\"` area red. That would look something like this.\n\n```css\ncta-modal [slot='button'] {\n  color: blue;\n}\n\ncta-modal [slot='modal'] {\n  color: red;\n}\n```\n\n### No close button\n\nHere is another scenario. Perhaps you want to have a static modal, with only a single toggle trigger to close it. If you intend to provide that yourself, you can hide the default close button with CSS such as this.\n\n```css\ncta-modal[static='true'] {\n  --cta-modal-close-display: none;\n}\n```\n\n### Dark mode\n\nIf you want to provide a different set of style overrides for users who prefer [dark mode](https://css-tricks.com/dark-modes-with-css/), you can scope your selector within a media query. This would make the modal background dark gray.\n\n```css\n@media (prefers-color-scheme: dark) {\n  cta-modal {\n    --cta-modal-dialog-background-color: #333;\n\n    /* Dark mode overrides here. */\n  }\n}\n```\n\nOr, you could scope the selector to a specific extra attribute of your choosing. Let's say some modals in your page need to be dark, whereas others do not. You might consider this approach.\n\n```css\ncta-modal {\n  --cta-modal-dialog-background-color: #fff;\n\n  /* Default overrides here. */\n}\n\ncta-modal[theme='dark'] {\n  --cta-modal-dialog-background-color: #333;\n\n  /* Dark mode overrides here. */\n}\n```\n\n---\n\nCreated by [Nathan Smith](http://twitter.com/nathansmith). Licensed under [MIT](https://en.wikipedia.org/wiki/MIT_License) and [GPL](https://en.wikipedia.org/wiki/GNU_General_Public_License).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnathansmith%2Fcta-modal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnathansmith%2Fcta-modal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnathansmith%2Fcta-modal/lists"}