{"id":13397949,"url":"https://github.com/toomuchdesign/offside","last_synced_at":"2025-04-04T22:06:37.148Z","repository":{"id":23128204,"uuid":"26482950","full_name":"toomuchdesign/offside","owner":"toomuchdesign","description":"Minimal JavaScript kit without library dependencies to push things off-canvas using just class manipulation.","archived":false,"fork":false,"pushed_at":"2024-06-16T17:08:35.000Z","size":202,"stargazers_count":277,"open_issues_count":2,"forks_count":23,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-10-30T01:37:04.591Z","etag":null,"topics":["css-transforms","off-canvas","off-canvas-menu"],"latest_commit_sha":null,"homepage":"http://toomuchdesign.github.io/offside/demos/typical/","language":"JavaScript","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/toomuchdesign.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","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":"2014-11-11T11:54:00.000Z","updated_at":"2024-09-03T16:20:51.000Z","dependencies_parsed_at":"2022-08-21T19:30:54.961Z","dependency_job_id":"7f23d4e7-9804-4c03-ae47-773c9b94bd97","html_url":"https://github.com/toomuchdesign/offside","commit_stats":{"total_commits":135,"total_committers":8,"mean_commits":16.875,"dds":"0.40740740740740744","last_synced_commit":"f4d48083d46bc0f836761698bc90bdf952da779f"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toomuchdesign%2Foffside","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toomuchdesign%2Foffside/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toomuchdesign%2Foffside/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toomuchdesign%2Foffside/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/toomuchdesign","download_url":"https://codeload.github.com/toomuchdesign/offside/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247256112,"owners_count":20909240,"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":["css-transforms","off-canvas","off-canvas-menu"],"created_at":"2024-07-30T18:01:56.816Z","updated_at":"2025-04-04T22:06:37.131Z","avatar_url":"https://github.com/toomuchdesign.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003cimg src=\"http://toomuchdesign.github.io/offside/demos/img/offside-logo.svg\" width=\"150\" alt=\"Offside.js shiny logo\"\u003e\n\u003c/p\u003e\n\n# Offside.js\n\n[![Build Status][ci-img]][ci]\n\n[ci-img]:                       https://travis-ci.org/toomuchdesign/offside.svg\n[ci]:                           https://travis-ci.org/toomuchdesign/offside\n\n**Offside.js** is a minimal JavaScript kit **without library dependencies** to push things off-canvas **using just class manipulation**. It's goal is to provide a super-lightweight, efficient and customizable way of handling off-canvas menus/elements on modern website and web applications.\n\n**Offside.js** comes with its own default stylesheet which make use of **CSS 3D transform**, but **you can write your own CSS** hooking your style with Offside classes. This ensures **super flexibility** and completely **decouples Offside.js from your style/markup**.\n\n## Demos\n\n- [Single element](http://toomuchdesign.github.io/offside/demos/single-element)\n- [Single element (without css 3dtransforms)](http://toomuchdesign.github.io/offside/demos/single-element-no-css-3d-transforms)\n- [Multiple elements](http://toomuchdesign.github.io/offside/demos/multiple-elements)\n- [Multiple elements (without css 3dtransforms)](http://toomuchdesign.github.io/offside/demos/multiple-elements-no-css-3d-transforms)\n- [Typical setting](http://toomuchdesign.github.io/offside/demos/typical)\n\n## Features:\n\n- Minimal DOM manipulations\n- No library dependencies\n- Uses CSS3 3D transforms (if you want to)\n- No injected style. Offside entirely relies on classes manipulations\n- BEM-like style\n- Degrades gracefully on browsers not supporting CSS3 3D transforms\n- Handles multiple off-canvas elements\n- Left/right off-canvas\n- Style agnostic\n- No need of extra classes or any specific markup.\n- Consumable as `commonJS`/`ES` module with a `require('offside-js')`\n\n## Browser Compatibility\n\nAll **modern browsers** and **ie9+**.\n\nOffside.js relies on **EventTarget.addEventListener / removeEventListener** and **querySelector / querySelectorAll** methods without any fallback.\n\nCheck relative browser compatibility:\n- [EventTarget.addEventListener / removeEventListener](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#Browser_compatibility)\n- [querySelector / querySelectorAll](http://caniuse.com/#search=queryselectorAll)\n\n## Usage instructions\n\n### Install:\nYou can install **Offside.js** as a [Bower](http://bower.io) or [NPM](http://www.npmjs.com) dependency.\n\n```sh\n# Bower\nbower install offside --save\n\n# NPM\nnpm install offside-js --save\n```\n\n### 1. Link files:\n\n```html\n  \u003c!-- Put these into the \u003chead\u003e --\u003e\n  \u003clink rel=\"stylesheet\" href=\"dist/offside.css\"\u003e\n  \u003cscript src=\"dist/offside.js\"\u003e\u003c/script\u003e\n```\n\n...or import as a module:\n\n```js\n  import 'offside-js/dist/offside.css';\n  import offside from 'offside-js';\n```\n\n### 2. Markup example:\n\n```html\n  \u003c!-- Off-canvas toggle button --\u003e\n  \u003cbutton type=\"button\" id=\"my-button\"\u003eOffside toggle\u003c/button\u003e\n\n  \u003c!-- Off-canvas element  --\u003e\n  \u003cnav id=\"my-menu\"\u003e\n    \u003cul\u003e\n      \u003cli\u003e\u003ca href=\"#\"\u003eHome\u003c/a\u003e\u003c/li\u003e\n      \u003cli\u003e\u003ca href=\"#\"\u003eAbout\u003c/a\u003e\u003c/li\u003e\n      \u003cli\u003e\u003ca href=\"#\"\u003eProjects\u003c/a\u003e\u003c/li\u003e\n      \u003cli\u003e\u003ca href=\"#\"\u003eContact\u003c/a\u003e\u003c/li\u003e\n    \u003c/ul\u003e\n  \u003c/nav\u003e\n\n  \u003c!-- Your Content --\u003e\n  \u003cdiv id=\"my-content-container\"\u003e\n    ...\n  \u003c/div\u003e\n```\n\nOffside.js is designed to work with your existing HTML.\n\nIt **doesn't pre-requires any specific markup**. When Offside initializes It just adds a few classes on existing DOM elements.\n\n\n### 3. Hook up the plugin:\n\n```html\n\u003c!-- Put this right before the \u003c/body\u003e closing tag --\u003e\n  \u003cscript\u003e\n\n    //Offside.js minimal setup\n    var myOffside = offside( '#my-menu', {\n\n        slidingElementsSelector:'#my-content-container',\n        buttonsSelector: '#my-button, .another-button',\n    });\n  \u003c/script\u003e\n```\n\n#### What are \"sliding elements\"?\n\n`slidingElementsSelector` is a selector list of all elements which slide out when an off-canvas element slides in. It's usually the page wrapper.\n\nUse it only when you need your page to slide together with you off-canvas element.\n\n\n### 4. Customizable options:\n\n```javascript\n  var myOffside = offside( '#my-menu', {\n\n      // Global offside options: affect all offside instances\n      slidingElementsSelector: '#my-content-container', // String: Sliding elements selectors ('#foo, #bar')\n      disableCss3dTransforms: false,                    // Disable CSS 3d Transforms support (for testing purposes)\n      debug: true,                                      // Boolean: If true, print errors in console\n\n      // Offside instance options: affect only this offside instance\n      buttonsSelector: '#my-button, .another-button',   // String: Offside toggle buttons selectors ('#foo, #bar')\n      slidingSide: 'right',                             // String: Offside element pushed on left or right\n      init: function(){},                               // Function: After init callback\n      beforeOpen: function(){},                         // Function: Before open callback\n      afterOpen: function(){},                          // Function: After open callback\n      beforeClose: function(){},                        // Function: Before close callback\n      afterClose: function(){},                         // Function: After close callback    \n\n  });\n```\n**Global offside options** are set when first Offside instance is created. This happens because **Offside factory** is created when the first `offside()` call occurs.\n\n\n## Public methods\n\nOffside.js plays well with your application. Each Offside instance exposes the following methods:\n\n`offsideInstance.toggle();`\n\n`offsideInstance.open();`\n\n`offsideInstance.close();`\n\n`offsideInstance.closeAll();`\n\n`offsideInstance.destroy();`\n\n\n## How does it work?\n\nWhen the first Offside element is initialized, a **singleton Offside factory** is created and used to return the first Offside instance. The factory keeps track of all initialized Offside elements.\n\nOffside.js is entirely based on **classes injection** and **custom callbacks**. No style is DOM injected. Never!\n\nClasses are injected in **just 3 elements**:\n  - \u003ccode\u003ebody\u003c/code\u003e\n  - \u003ccode\u003eoff-canvas elements\u003c/code\u003e\n  - \u003ccode\u003esliding elements\u003c/code\u003e\n\nHere a brief explanation.\n\n### 1. Initialization\n\n#### Callbacks fired:\n- \u003ccode\u003einit()\u003c/code\u003e\n\n#### Injected classes:\n```html\n  \u003cbody class=\"offside-js--init\"\u003e\n\n    \u003c!-- Off-canvas element --\u003e\n    \u003cdiv class=\"offside offside--left\"\u003e\n\n    \u003c!-- Sliding element --\u003e\n    \u003cdiv class=\"offside-sliding-element\u003e\n```\n\n### 2. First offside open\n\nOn first interaction with an Offside instance, \u003ccode\u003eoffside-js--interact\u003c/code\u003e class is added to body. Sometime useful to avoid unexpected CSS behaviours on startup.\n\n#### Injected classes:\n```html\n  \u003cbody class=\"offside-js--init offside-js--interact\"\u003e\n```\n\n### 3. Offside open\n\n#### Callbacks fired:\n- \u003ccode\u003ebeforeOpen()\u003c/code\u003e\n- \u003ccode\u003eafterOpen()\u003c/code\u003e\n\n#### Injected classes:\n```html\n  \u003cbody class=\"offside-js--init offside-js--transitions offside-js--is-open offside-js--is-left\"\u003e\n\n  \u003c!-- Off-canvas element --\u003e\n  \u003cdiv class=\"offside offside--left is-open\"\u003e\n```\n\n### 4. Offside closed\n\n#### Callbacks fired:\n- \u003ccode\u003ebeforeClose()\u003c/code\u003e\n- \u003ccode\u003eafterClose()\u003c/code\u003e\n\n#### Injected classes:\n```html\n  \u003cbody class=\"offside-js--init offside-js--transitions\"\u003e\n\n  \u003c!-- Off-canvas element --\u003e\n  \u003cdiv class=\"offside offside--left is-open\"\u003e\n```\n\n## Tips and Tricks\n\n- Set **off-canvas elements width** directly into `offside.css` stylesheet.\n- Replace `offside.css` with `offside-no-css-3d-transforms.css` stylesheet and and set `disableCss3dTransforms` setting to `true` to try the fallback.\n\n### Do you really need a JS plugin?\nIf you need to set up a simple off-canvas menu, you might not need JS! [This Chris Coyer's post](https://css-tricks.com/off-canvas-menu-with-css-target/) explains a nice solution which relies on **CSS :target selector**. ie9+ only!\n\n\n## Known bugs\n\n### Off-canvas elements blocked on the page\n\nOn some old mobile browsers ( as Android 2.2.2 FroYo ) off-canvas elements won't get out the page on page load.\n\nThis happens because their internal browser do not officially support CSS transforms (see [can I use chart](http://caniuse.com/#feat=transforms3d)), but, according to my experience, they only support it partially. Infact these browser are able to pass Offside CSS 3dTransform test and do not activate Offside fallback strategy.\n\nOffside instances are normally set to `position: fixed` and these browser are not able to apply `translate3d` transform to fixed positioned element.\n\nAn easy - but simplistic - fix, is to switch `.offside` position to `absolute` and properly set a relative position to a parent element (of course, it might  have an impact on your page layout):\n\n```css\n.offside {\n    position: absolute;\n}\n```\n\n### Off-canvas elements inside a sliding element\n\nLike this:\n\n```html\n  \u003c!-- Sliding element --\u003e\n  \u003cdiv id=\"my-page-wrapper\"\u003e\n\n    \u003c!-- Off-canvas element  --\u003e\n    \u003cnav id=\"my-offside-element\"\u003e\n      ...\n    \u003c/nav\u003e\n    ...\n  \u003c/div\u003e\n```\n\nWhen an element receives a 3D transform style, It creates a containing block for all its descendants that have been set to `position: fixed` or `position: absolute`. Read more [here](http://meyerweb.com/eric/thoughts/2011/09/12/un-fixing-fixed-elements-with-css-transforms).\n\n\n## To do's\n\nSome ideas for the future. If you'd like to see any of the following realized, please contribute or open an issue.\n\n- Expose Offside factory initialization method *(now called on first Offside instance initialization)*\n- Customizable Offside classes\n- Declare a different set of sliding elements for each Offside instance\n- Add an option to let more than one Offside instance open at same time\n- Replace GruntJS with npm script tasks\n- Replace callbacks with global events *(maybe)*\n- Remove CSS 3D Transform Support check *(maybe)*\n\n## Working on the repository\n\nMake sure you have **node** and **npm** on your machine. When ready, you can install Offside.js dependencies:\n\n```sh\nnpm install\n# or\nnpm run setup\n```\n\nOnce everything is set up, work in `src` directory and build `dist` files using:\n\n```sh\nnpm run watch\n# or\nnpm run build\n```\n\n### Updating gh-pages branch (just a reminder)\n\n```sh\ngit checkout gh-pages\ngit checkout master demos\ngit checkout master dist\n```\n\n## Versioning\n\nStarting from version **1.3.0**, this library uses [semantic versioning](http://semver.org).\n\n## Thanks to\n\n- [Christopher Yee's pushy.js](https://github.com/christophery/pushy)\n- [Viljami Salminen's responsive-nav.js](https://github.com/viljamis/responsive-nav.js)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoomuchdesign%2Foffside","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftoomuchdesign%2Foffside","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoomuchdesign%2Foffside/lists"}