A small, dependency-light UI component that toggles a website between light and dark themes. It is implemented with plain HTML, CSS (or SCSS), and JavaScript (uses jQuery for DOM convenience). The component persists the selected theme in localStorage so user preference is remembered across visits.
- Lightweight: implemented with HTML/CSS/JS
- Two provided variants:
- simple-version — standalone HTML/CSS/JS files (no build tools required)
- scss-version — source SCSS files and a Gulp build that outputs compiled CSS/JS into
dist/
- Saves theme preference in browser
localStorage
- The toggle is a checkbox input that, when checked, sets
localStorage['theme-dark'] = 'true'and adds thetheme-darkclass to<body>. - When the page loads the script reads
localStorageand applies the theme automatically.
You can try the project without installing anything:
- Open
simple-version/index.htmlin your browser for a minimal example. - Open
scss-version/index.htmlafter building (dist/must be created — see Build steps).
<div class="Switch">
<input id="switch-toggle-btn" class="SwitchToggle" type="checkbox" />
<label for="switch-toggle-btn">
<span class="material-icons-outlined">light_mode</span>
<span class="material-icons-outlined">dark_mode</span>
</label>
</div>
<!-- jQuery (required) -->
<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
<!-- Component script -->
<script src="path/to/script.js"></script>If you want to work with the SCSS source and use the build pipeline:
- Install dependencies
cd scss-version
npm install- Run Gulp (this will build CSS/JS into
dist/, start a watcher and launch BrowserSync):
npx gulp
# or install gulp-cli globally and run
# npm install --global gulp-cli
# gulpNote: The repository includes a gulpfile.js that compiles SCSS, autoprefixes and minifies CSS, babel-transpiles and uglifies JS, and serves the project with BrowserSync.
- Include the markup above where you want the switch to appear.
- Ensure jQuery is loaded before the component script.
- Optionally customize colors in CSS/SCSS — the simple-version uses CSS custom properties and class
theme-dark. - The component stores a
theme-darkkey inlocalStoragewith value'true'or'false'.
- SCSS version provides variables under
src/scss/variables/to change colors, fonts, or theme defaults. - You can change the icon set or replace the icons with text or SVGs.
- The toggle is implemented as a native checkbox which provides basic keyboard support.
- Improvements to consider: add
aria-labeland more explicit focus styles, announce theme change to assistive tech, and ensure sufficient color contrast for each theme.
├─ simple-version/
│ ├─ index.html
│ ├─ script.js
│ └─ style.css
└─ scss-version/
├─ gulpfile.js
├─ package.json
└─ src/
├─ js/
└─ scss/
- Fork the repo, make changes in a feature branch, and open a pull request with a description of your changes.
- For SCSS work, run
npm installinscss-version, thennpx gulpto build and test.
- Convert the component to a framework-friendly variant (React) and publish as an npm package.
- Add unit and integration tests for the JS logic (e.g., verify localStorage behavior).
- Improve accessibility (ARIA announcements, focus management, keyboard-only support).
- Add an option to follow the system color scheme (
prefers-color-scheme) by default. - Add a small demo page with multiple components and examples showcasing customization.
- Add an automated CI workflow to run linting and tests and publish bundles.
This project is licensed under the MIT License. See the LICENSE file for details.
Made with ❤️ by Pamela Santos