{"id":13780092,"url":"https://github.com/ava-cassiopeia/simple-switch","last_synced_at":"2025-05-11T13:31:33.132Z","repository":{"id":39844614,"uuid":"93962473","full_name":"ava-cassiopeia/simple-switch","owner":"ava-cassiopeia","description":"Vanilla JS/CSS Switch UI element","archived":false,"fork":false,"pushed_at":"2023-02-04T05:00:10.000Z","size":2816,"stargazers_count":18,"open_issues_count":6,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-05-21T02:45:02.427Z","etag":null,"topics":["checkbox","javascript","js","sass","switch","ui","ui-components","vanilla-js","web-component","webpack"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ava-cassiopeia.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-06-10T20:01:41.000Z","updated_at":"2023-01-31T16:50:27.000Z","dependencies_parsed_at":"2023-02-18T13:50:14.847Z","dependency_job_id":null,"html_url":"https://github.com/ava-cassiopeia/simple-switch","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ava-cassiopeia%2Fsimple-switch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ava-cassiopeia%2Fsimple-switch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ava-cassiopeia%2Fsimple-switch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ava-cassiopeia%2Fsimple-switch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ava-cassiopeia","download_url":"https://codeload.github.com/ava-cassiopeia/simple-switch/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224855026,"owners_count":17380959,"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":["checkbox","javascript","js","sass","switch","ui","ui-components","vanilla-js","web-component","webpack"],"created_at":"2024-08-03T18:01:12.240Z","updated_at":"2024-11-17T15:30:54.204Z","avatar_url":"https://github.com/ava-cassiopeia.png","language":"JavaScript","readme":"# Simple Switch\n\n[![npm version](https://badge.fury.io/js/a-simple-switch.svg)](https://badge.fury.io/js/a-simple-switch)\n[![Build](https://github.com/ava-cassiopeia/simple-switch/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/ava-cassiopeia/simple-switch/actions/workflows/test.yml)\n\nSimple, accessible, performant implementation of the Switch UI element.\n\n![Demo gif of switch in both material and normal mode](https://user-images.githubusercontent.com/6314286/27511703-357cf59c-58e8-11e7-81b7-cf87b1a0408a.gif)\u003cbr /\u003e\n*Above shows both the normal and 'material' mode available for the switch*\n\n**Features:**\n\n- Vanilla JS/CSS: doesn't require any outside library to function\n- Accessible: works properly with screenreaders and the ARIA spec\n- Performant: uses proper layering and transitioning to ensure high performance\n\n---\n\n- [Installation](#installation)\n  - [Installing the Javascript](#installing-the-javascript)\n  - [Installing the CSS](#installing-the-css)\n  - [Installing the SASS](#installing-the-sass)\n- [Creating a Simple Switch](#creating-a-simple-switch)\n  - [Automatically Creating Switches](#automatically-creating-switches)\n  - [Manually Creating Switches](#manually-creating-switches)\n- [SASS Variables](#sass-variables)\n- [Controlling the switch via JavaScript](#controlling-the-switch-via-javascript)\n- [Contributing](#contributing)\n\n## Installation\n\nTo install the Switch code, you will need to in some way include the Simple\nSwitch Javascript and CSS into your page/build. Please follow the relevant\ninstructions below for more information.\n\nTo get the latest minified/production ready files, please see the\n[releases page](https://github.com/aeolingamenfel/simple-switch/releases).\n\n### Installing the Javascript\n\nThe Javascript is available as a NPM package, buildable through Webpack, or as\na minified/uglified file that can be directly imported into the page.\n\nThe minified Javascript file is available on the\n[releases page](https://github.com/aeolingamenfel/simple-switch/releases),\nwithin the release `.zip` file, under `js/`.\n\n---\n\nAlternatively, the Webpack package can be installed by running:\n\n```\nnpm i --save a-simple-switch\n```\n\nAnd then importing it into your webpack build by saying:\n\n```Javascript\nimport * as SimpleSwitch from \"a-simple-switch\";\n```\n\n### Installing the CSS\n\nYou can install the CSS by downloading the compiled CSS file from the\n[releases page](https://github.com/aeolingamenfel/simple-switch/releases),\nunder `css/`.\n\n### Installing the SASS\n\nYou can import the relevant SASS file into your SASS build by either downloading\nthe latest release from the\n[releases page](https://github.com/aeolingamenfel/simple-switch/releases) and\ngrabbing the SASS file from the `sass/` directory in the release, *or* you may\ndirectly import it from the source code:\n\n```SASS\n@import \"path/to/SimpleSwitch/src/sass/SimpleSwitch.scss\";\n```\n\n## Creating a Simple Switch\n\nThere are two ways to create a Simple Switch. On page load, the Simple Switch\ncode will automatically detect checkboxes that are flagged as switches, and\nupgrade them, *or* you may manually instantiate a switch. See below for more\ndetails.\n\n### Automatically Creating Switches\n\nTo have a switch be automatically upgraded, simply add the `data-type` attribute\nto any checkbox-type input that you want upgraded, and set that attribute to the\nvalue of `simple-switch`. Then, at the end of your `\u003cbody\u003e` tag, simply call\n`SimpleSwitch.init()` to initialize all of the switches marked as noted above.\n\nIn addition, the Switch has an additional \"material\" mode, which can be toggled\nper switch using the `data-material` attribute.\n\n*Example:*\n\nStandard Switch:\n\n```HTML\n\u003cinput type=\"checkbox\" name=\"my-checkbox\" data-type=\"simple-switch\" /\u003e\n```\n\nMaterial Switch:\n\n```HTML\n\u003cinput type=\"checkbox\" name=\"my-checkbox\" data-type=\"simple-switch\" data-material=\"true\" /\u003e\n```\n\nJavascript Setup:\n\n```HTML\n\u003c!-- ^^ Rest of your page above ^^ --\u003e\n    \u003cscript type=\"text/javascript\"\u003e\n        SimpleSwitch.init();\n    \u003c/script\u003e\n\u003c/body\u003e\n```\n\n### Parameters\n\nThere are a few different parameters that can be provided to configure SimpleSwitch:\n\n**Parameters:**\n\n| Name | Index | Value | Default Value | Required? | Description |\n| ---- | ----- | ----- | ------------- | --------- | ----------- |\n| Element | `element` | HTMLElement | `null` | Yes* | This is the checkbox HTMLElement that will be upgraded to a Switch. Required if the `selector` parameter is not set |\n| Selector | `selector` | String | `null` | Yes* | This is the CSS selector that specifies the checkbox HTMLElement that will be upgraded to a Switch. Required if the `element` parameter is not set |\n| Material Style | `material` | Boolean | `false` | No | If set, will set the Switch to have an alternative style that matches the [Material.io spec](https://material.io/guidelines/components/selection-controls.html#selection-controls-switch) for Switches |\n| Update Size from Font | `matchSizeToFont` | Boolean | `false` | No | If set, will cause the Switch to attempt to match its size to the font size of the containing element |\n\n### Manually Creating Switches\n\nYou may also manually instantiate a switch, which may be useful for\nlazily-loaded UI elements or parts of the page. The `Switch` class which handles\nupgrading and controlling Switches is available under the `SimpleSwitch`\nnamespace.\n\n*Example:*\n\nHTML:\n\n```HTML\n\u003cinput type=\"checkbox\" name=\"my-checkbox\" id=\"my-checkbox\" /\u003e\n```\n\nJavascript:\n\n```Javascript\nlet myCheckbox = document.getElementById(\"my-checkbox\");\n\nnew SimpleSwitch.Switch({\n    element: myCheckbox,\n    material: true\n});\n```\n\n## SASS Variables\n\nIf you have chosen to include the SASS version of the styles for the Switch\ninto your project, there are a number of variables available to you to override\nto customize the look and feel of the Switch. See more information about these\nbelow.\n\n| Name | Value | Default Value | Description |\n| ---- | ----- | ------------- | ----------- |\n| `$simple-switch_color` | Color | `#f44336` | Determines the color of the Switch, which isn't visible until the user has checked/switched \"on\" the switch |\n| `$simple-switch_focus-color` | Color | `#03A9F4` | Determines the color that the outline around the Switch will be, where the outline only appears when the Switch gains focus |\n| `$simple-switch_focus-ring-size` | Size Unit (px) | `7px` | On the Material version of the Switch, determines how much larger the radius of the focus ring is than the handle of the Switch |\n| `$simple-switch_handle-color` | Color | `#fff` | Determines the color of the Switch's handle |\n| `$simple-switch_outline-size` | Size Unit (px) | `3px` | Determines how thick the outline around the Switch's track is, both for the focus ring and the padding around the actual handle of the Switch |\n| `$simple-switch_size` | Size Unit (px) | `12px` | By default, the Switch matches its size to the inherited `font-size` of the Switch, so that it can match any label/text next to it in terms of size. However, on older browsers that don't support CSS Variables, this is the fallback that the CSS goes to |\n| `$simple-switch_switch-speed` | Timing Unit | `250ms` | The amount of time it takes the Switch animation to finish moving between the \"on\" and \"off\" state |\n| `$simple-switch_tray-color` | Color | `#ccc` | The color of the tray of the Switch |\n\n## Controlling the switch via JavaScript\n\nThe switch can be toggled via JavaScript:\n\n```js\n  SimpleSwitch.toggle(checkboxElement);\n```\n\nIt can also be set specifically to on or off:\n\n```js\n  SimpleSwitch.toggle(checkboxElement, true);\n\n  SimpleSwitch.toggle(checkboxElement, false);\n```\n\n## Contributing\n\nFeel free to send pull requests, issues, feature requests, etc. There is no\nSLA for responses on this repo, but I trying to respond to issues and PRs in a\ntimely manner.\n\nWhen sending PRs please follow the Google TypeScript style guide\n([style guide link](https://google.github.io/styleguide/tsguide.html)) and try\nto add test coverage where possible.\n\nMost of the codebase and NPM commands (like `npm test`) should work\nout-of-the-box, but you will need Chrome installed to run headless tests.\n","funding_links":[],"categories":["Components"],"sub_categories":["Switches"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fava-cassiopeia%2Fsimple-switch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fava-cassiopeia%2Fsimple-switch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fava-cassiopeia%2Fsimple-switch/lists"}