{"id":16594321,"url":"https://github.com/jh3y/doormat","last_synced_at":"2025-03-16T21:30:42.134Z","repository":{"id":14642472,"uuid":"17360216","full_name":"jh3y/doormat","owner":"jh3y","description":"Let's take a scroll!","archived":false,"fork":false,"pushed_at":"2017-08-07T16:18:12.000Z","size":767,"stargazers_count":110,"open_issues_count":0,"forks_count":13,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-12-12T09:17:35.961Z","etag":null,"topics":["css","doormat","layout","site-navigation","ui","ux"],"latest_commit_sha":null,"homepage":"https://jh3y.github.io/doormat","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jh3y.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":"2014-03-03T08:53:00.000Z","updated_at":"2024-08-14T09:29:18.000Z","dependencies_parsed_at":"2022-08-23T17:10:35.228Z","dependency_job_id":null,"html_url":"https://github.com/jh3y/doormat","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jh3y%2Fdoormat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jh3y%2Fdoormat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jh3y%2Fdoormat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jh3y%2Fdoormat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jh3y","download_url":"https://codeload.github.com/jh3y/doormat/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243830933,"owners_count":20354852,"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","doormat","layout","site-navigation","ui","ux"],"created_at":"2024-10-11T23:45:55.056Z","updated_at":"2025-03-16T21:30:41.807Z","avatar_url":"https://github.com/jh3y.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![NPM](https://nodei.co/npm/doormat.png?downloads=true)](https://nodei.co/npm/doormat/)\n\n[![Build Status](https://travis-ci.org/jh3y/doormat.svg?branch=master)](https://travis-ci.org/jh3y/doormat)\n![img](https://img.shields.io/badge/license-MIT-blue.svg)\n![img](https://img.shields.io/badge/dependencies-none-green.svg)\n[![styled with prettier](https://img.shields.io/badge/styled_with-prettier-ff69b4.svg)](https://github.com/prettier/prettier)\n\n# Doormat 👞👡\n_an alternative way to traverse through your site content_ 😎\n\n![alt tag](https://raw.github.com/jh3y/pics/master/doormat/GeneralUsage.gif)\n\n## Index\n\n* [How](https://github.com/jh3y/doormat#how)\n* [Features](https://github.com/jh3y/doormat#features)\n* [Browser support](https://github.com/jh3y/doormat#browser-support)\n* [Usage](https://github.com/jh3y/doormat#usage)\n  * [Options](https://github.com/jh3y/doormat#options)\n  * [API](https://github.com/jh3y/doormat#api)\n  * [Events](https://github.com/jh3y/doormat#events)\n* [curtain.js?](https://github.com/jh3y/doormat#curtain.js?)\n* [Customisation](https://github.com/jh3y/doormat#customisation)\n  * [UI Effects](https://github.com/jh3y/doormat#ui-effects)\n  * [Caveats](https://github.com/jh3y/doormat#caveats)\n  * [Roll your own classes](https://github.com/jh3y/doormat#roll-your-own-classes)\n* [Development](https://github.com/jh3y/doormat#development)\n* [Contributing](https://github.com/jh3y/doormat#contributing)\n* [License](https://github.com/jh3y/doormat#license)\n\n## How\nThe trick is possible by making sections of the page `position: fixed` and `position: absolute` whilst setting a height for the container element equal to the combined height of the page sections.\n\nPage sections are given an appropriate `top` value that gives some buffer space for scrolling and give the parallax like illusion against whichever section is currently `position: fixed`.\n\nDependent on the panel mode, as the `window` is scrolled panels come into or move out of the viewport to either reveal or cover up fixed position content.\n\n## Features\n* Provides alternative way to traverse content\n* Configurable behavior\n* Inbound and outbound traversal modes\n* Panel snapping to either viewport or as a means of traversing panels\n* API for programmatically traversing content\n* Responsive\n* Animated scrolling\n* Simple to create custom effects/behavior with CSS with many possibilities.\n* Supports overflowing content in outbound mode(_refer to caveats_:sweat_smile:)\n* No dependencies! :tada:\n* Scroll/Resize optimization via `requestAnimationFrame`\n\n![alt tag](https://raw.github.com/jh3y/pics/master/doormat/SnapViewport.gif)\n\n## Browser support\n| Chrome  | Firefox | Safari  | Opera   | Edge    | IE       |\n|:-------:|:-------:|:-------:|:-------:|:-------:|:--------:|\n| :smile: | :smile: | :smile: | :smile: | :smile: | :smile:  |\n\n`v5` makes use of `requestAnimationFrame`, `viewport` units and the `Event` API. Most browsers should play nice except `Opera Mini` :-1:. `IE` support should be fine in version `11`.\n\n## Usage\nTo create your doormat.\n\n1. Include `doormat{.min}.js` and `doormat{.min}.css` in your page/bundle.\n\n2. Create your DOM/Page structure. The containing element needs the classname `dm`. This could be `body`. `doormat` uses panels for each section of content. Therefore, the children of our container need the class `dm-pnl`. `ol` and `ul` make good container elements :wink: A structure like the following is ideal.\n\n  ```html̨\n    \u003cbody\u003e\n      \u003col class=\"dm\"\u003e\n        \u003cli class=\"dm__pnl\"\u003eAwesome\u003c/li\u003e\n        \u003cli class=\"dm__pnl\"\u003eSite\u003c/li\u003e\n        \u003cli class=\"dm__pnl\"\u003eContent\u003c/li\u003e\n      \u003c/ol\u003e\n      \u003cscript src=\"doormat.min.js\"/\u003e\n    \u003c/body\u003e\n  ```\n\n3. Invoke the `Doormat` function passing in desired [options](#Options)(_explained below_) as a parameter;\n\n  ```javascript\n  document.addEventListener('DOMContentLoaded', function() {\n    var myDoormat = new Doormat();\n  });\n  ```\n\n### Options\n* `{number} snapDebounce - defaults to 150`: No need to trigger snapping behavior on every scroll so `snapDebounce` defines a debouncing duration in ms.\n* `{number} scrollDuration - defaults to 250`: Defines the default duration in ms that a panel takes to snap to place or the duration of a programmatic doormat scroll that isn't overridden with the optional parameter.\n* `{string} snapMode - defaults to 'viewport'`: Defines the \"snap\" style of `Doormat` panels. Whether it be `viewport` style, `travel` style or disabled with `false`. Setting to `false` will mean that users can scroll content so that it doesn't sit flush in the viewport.\n* `{string} mode - defaults to 'outbound'`: Defines the traversal style. `outbound` will make panels slide out to the top of the viewport revealing content underneath. `inbound` will make panels slide in from the bottom covering content.\n* `{number} snapThreshold - defaults to 30`: Define the percentage of the viewport that will trigger a \"snap\". For example, you start scrolling a panel but no more than `30%` of the viewport height. You stop scrolling and because `snapMode` is set to `viewport`, the panel scrolls back to fit flush with the viewport again :+1:\n\n![alt tag](https://raw.github.com/jh3y/pics/master/doormat/Inbound.gif)\n\n### API\n* `{number} activeIndex`: Getter for current active panel index. Useful for conditionals where content should only appear at certain times etc.\n* `{Object} active`: Getter for current active panel element.\n* `next`: Function to scroll to next panel.\n* `prev`: Function to scroll to previous panel.\n* `{Array} panels`: Getter for panels collection.\n* `reset`: Function to reset Doormat instance. Used on viewport changes. Will instantly scroll to top with no animation and  set first panel as active.\n* `{number} scrollPos`: Getter for current scroll position of instance.\n* `scrollTo({number} scrollPosition, ?{number} speed)`: Function for scrolling to a specific position within instance. Accepts optional `speed` parameter in ms.\n* `scrollToPanel({number} panelIndex, ?{number} speed)`:\nFunction for scrolling to a specific panel. Accepts optional `speed` parameter in ms.\n\n![alt tag](https://raw.github.com/jh3y/pics/master/doormat/ButtonTravel.gif)\n\n### Events\n`Doormat` offers an even that can be bound to for observing when a new panel becomes active. The event is `doormat:update`. Consider the following example that can be used for customisation to show controls once scrolled past the first panel :sunglasses:\n```js\nwindow.addEventListener('doormat:update', (e) =\u003e {\n  if (doormatInstance.activeIndex \u003e 1)\n    document.body.classList.add('show-controls')\n  else\n    document.body.classList.remove('show-controls')\n})\n```\n\n## curtain.js?\nUnfortunately, `curtain.js` is no longer maintained and there were reports of issues with newer versions of jQuery.\n\n`curtain.js` is a more feature rich solution and provides some different behavior and hooks. It does however depend on `jQuery`.\n\nI was unaware of `curtain.js` when creating `Doormat`. Initially, I was experimenting with different implementations of parallax style effects and messing about with viewport units.\n\nMy aim with `Doormat` was to create the effect but keep the solution minimal with no dependencies. It was a result of curiosity and playing with code.\n\n## Customisation\n### UI Effects\nOne feature I like with `Doormat` is the ability to create custom effects with relative ease using CSS or conditionally based on the current active panel index of a `Doormat` instance.\n\n![alt tag](https://raw.github.com/jh3y/pics/master/doormat/Customise.gif)\n\nFor example, the effects in the above `GIF` are created by leveraging `CSS` transitions based on the current active panel of an instance. The important parts are;\n\n```css\n.dm-panel__content {\n  opacity: 0;\n  transform: scale(0);\n  transition: opacity .25s ease 0s, transform .25s ease 0s;\n}\n\n.dm-panel--active .dm-panel__content {\n  opacity: 1;\n  transform: scale(1);\n}\n```\n\n### Caveats\n* If you use `inbound` mode, content larger than the viewport will get cut off as opposed to when using `outbound` mode. Solution? Make the content of the active panel scrollable :nerd_face:\n\n```css\n  .dm-panel--active .dm-panel__content {\n    overflow: auto;\n  }\n```\n\n### Roll your own classes\nThe classes for `Doormat` are config driven with `doormat.config.json`. In here you can alter the classnames for elements to your desire.\n\n__Important::__ If you change the classnames in the config, you will also need to update any reference to them from within the JavaScript source. For example, by altering the `classes` property on the `Doormat` class.\n\nChange the config and then run the build task with `make build`.\n\n\n\n## Development\nWant to play with the code?\n\n1. Fork and clone or simply clone the repo direct.\n\n        git clone https://github.com/jh3y/doormat.git\n\n2. Navigate into the repo and run the setup task;\n\n        cd doormat\n        make setup\n\n3. Run the `develop` task to get up and running with `browser-sync` etc.\n\n        make develop\n\n__NOTE::__ See all available build tasks by simply running `make` in the root of the directory :+1:\n```shell\n  make\n```\n\n![alt tag](https://raw.github.com/jh3y/pics/master/doormat/SnapTravel.gif)\n\n## Contributing\nDon't hesitate to post an issue or suggestion or get in touch by tweeting me [@_jh3y](https://twitter.com/_jh3y)!\n\n## License\nMIT\n\njh3y 2017\n\n-----\nImages courtesy of [Unsplash](https://unsplash.com/search/kitty) :cat:\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjh3y%2Fdoormat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjh3y%2Fdoormat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjh3y%2Fdoormat/lists"}