{"id":18389572,"url":"https://github.com/anseki/overflow-android","last_synced_at":"2025-04-07T02:34:32.562Z","repository":{"id":20207492,"uuid":"23478966","full_name":"anseki/overflow-android","owner":"anseki","description":"Implement the inertia scroll for `overflow` element. And the polyfill for `overflow:scroll` / `overflow:auto` and `element.scrollLeft` / `element.scrollTop` on Android browser.","archived":false,"fork":false,"pushed_at":"2022-08-19T03:23:42.000Z","size":1986,"stargazers_count":9,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-22T11:44:59.914Z","etag":null,"topics":["android","css-animations","desktop","drag","element-scrolls","flicks","inertia","inertia-scroll","inertial","javascript","overflow","polyfill","scroll","scrollbar","scrollleft","scrolltop","swipe"],"latest_commit_sha":null,"homepage":"http://anseki.github.io/overflow-android/","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/anseki.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}},"created_at":"2014-08-29T21:58:22.000Z","updated_at":"2025-02-28T17:01:36.000Z","dependencies_parsed_at":"2022-08-28T10:22:54.629Z","dependency_job_id":null,"html_url":"https://github.com/anseki/overflow-android","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anseki%2Foverflow-android","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anseki%2Foverflow-android/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anseki%2Foverflow-android/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anseki%2Foverflow-android/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/anseki","download_url":"https://codeload.github.com/anseki/overflow-android/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247583493,"owners_count":20962042,"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":["android","css-animations","desktop","drag","element-scrolls","flicks","inertia","inertia-scroll","inertial","javascript","overflow","polyfill","scroll","scrollbar","scrollleft","scrolltop","swipe"],"created_at":"2024-11-06T01:43:45.517Z","updated_at":"2025-04-07T02:34:27.552Z","avatar_url":"https://github.com/anseki.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OverflowAndroid\n\n[![npm](https://img.shields.io/npm/v/overflowandroid.svg)](https://www.npmjs.com/package/overflowandroid) [![GitHub issues](https://img.shields.io/github/issues/anseki/overflow-android.svg)](https://github.com/anseki/overflow-android/issues) [![David](https://img.shields.io/david/anseki/overflow-android.svg)](package.json) [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\nImplement the inertia scroll for `overflow` element. And the polyfill for `overflow:scroll` / `overflow:auto` and `element.scrollLeft` / `element.scrollTop` on Android browser.\n\nThe desktop can implement UI that scrolls by mouse drag, inertia scroll like touch device. And problems of Android browser are solved.\n\n[![ss-01](ss-01.gif)](http://anseki.github.io/overflow-android/)\n\nAndroid browser has problems as below:\n\n- `overflow:scroll` and `overflow:auto` don't work on Android 2.x. The elements don't accept scroll operations (swipe, flick, drag, etc.).\n- `element.scrollLeft` and `element.scrollTop` don't work on Android 4.0.x. The elements can't scroll via JavaScript. Strange to say, the element that is set `overflow:hidden` can scroll. But of course that element doesn't accept scroll operations.\n\nOverflowAndroid solves problems above.\n\n**See \u003ca href=\"http://anseki.github.io/overflow-android/\"\u003eDEMO\u003c/a\u003e**\n\n## Usage\n\n[Hammer.js](http://hammerjs.github.io/) is required.\n\n```html\n\u003cscript src=\"hammer.min.js\"\u003e\u003c/script\u003e\n\u003cscript src=\"overflow-android.min.js\"\u003e\u003c/script\u003e\n```\n\n```html\n\u003c!-- This `overflow:auto` isn't necessary. It works on desktop PC as native. --\u003e\n\u003cdiv id=\"view\" style=\"overflow: auto; width: 300px; height: 300px;\"\u003e  \u003c!-- Like an iframe window --\u003e\n  \u003cimg src=\"photo.jpg\" width=\"900\" height=\"600\" alt=\"sample\"\u003e         \u003c!-- Like an iframe document --\u003e\n\u003c/div\u003e\n```\n\n```js\nvar element = document.getElementById('view');\nnew OverflowAndroid(element);\n// Now, the element accepts scroll operations (swipe, flick, drag, etc.).\n\n// And it can scroll via scrollLeft/scrollTop.\nelement.scrollLeft = 30;\n```\n\n## Constructor\n\n```js\noverflowA = new OverflowAndroid(element)\n```\n\nThe `OverflowAndroid` constructor accepts an element that is scrolling frame. It gets a first child element that includes contents and it moves when scrolling. The specified element like an `iframe` window, and the first child element like an `iframe` document.  \nThat has already finished. Now, the specified element accepts scroll operations (swipe, flick, drag, etc.), and it can scroll via `scrollLeft`/`scrollTop`.  \nAnd the instance that is returned by constructor has some methods. (see below)  \n*NOTE:* The contents that is included in specified element other than a first child element of it are ignored.\n\n## Methods\n\n### `scrollLeft`\n\n```js\ncurrentLeft = overflowA.scrollLeft([newLeft])\n```\n\nReturn the number of pixels that the element's content is scrolled to the left. If an argument is given, the element scrolls to specified position and it is returned.  \nThis work equals `element.scrollLeft` property.\n\n### `scrollTop`\n\n```js\ncurrentTop = overflowA.scrollTop([newTop])\n```\n\nReturn the number of pixels that the element's content is scrolled upward. If an argument is given, the element scrolls to specified position and it is returned.  \nThis work equals `element.scrollTop` property.\n\n### `scroll`\n\n```js\ncurrentLeftTop = overflowA.scroll([newLeft[, newTop]])\n```\n\nReturn the Object that has `left` as the number of pixels that the element's content is scrolled to the left, and `top` as the number of pixels that the element's content is scrolled upward. If arguments are given, the element scrolls to specified position and it is returned.\n\n### `stop`\n\n```js\nself = overflowA.stop()\n```\n\nStop scroll immediately.\n\n### `initSize`\n\n```js\nself = overflowA.initSize([newLeft[, newTop]])\n```\n\nOverflowAndroid computes the size of elements for scroll. It computes again automatically when a window is resized. Therefore you usually don't need to call this method.  \nIf you changed the size of elements, you must call this method. If arguments are given, the size of elements is computed and the element scrolls to specified position.\n\n## Properties\n\n### `clientWidth`, `clientHeight`\n\n```js\nwidth = overflowA.clientWidth\n```\n\n```js\nheight = overflowA.clientHeight\n```\n\nSize of the element's view-area. This area is `padding-box` in CSS. In other words, a part of contents in child element that has this size is shown.\n\n### `scrollWidth`, `scrollHeight`\n\n```js\nwidth = overflowA.scrollWidth\n```\n\n```js\nheight = overflowA.scrollHeight\n```\n\nSize of scrolled area. This area is all of contents in child element that includes margins, and padding of target element.  \nIn CSS, `border-box` of child element + `margin`s of child element + `padding`s of target element. Therefore this might differ from `element.scrollWidth`/`element.scrollHeight`.\n\n## Event\n\nThe `scroll` event is fired when the target element has been scrolled. The `Event` object that is passed to event listeners has an additional property below.\n\n### `inertia`\n\nType: Boolean\n\nIndicate whether the current event was fired by inertia scroll after fast scroll operations. i.e. user isn't touching the element now, if this is `true`.\n\nExample:\n\n```js\nelement.addEventListener('scroll', function(e) {\n  console.log('left: ' + e.target.scrollLeft +\n    ', top: ' + e.target.scrollTop + ', more scrolling: ' + e.inertia);\n}, false);\n```\n\n## Options\n\nYou can tune the behavior of OverflowAndroid via options below.\n\n### `OverflowAndroid.enable`\n\nBy default, OverflowAndroid works only touch-device. You can control the working or not via specifying a boolean to this option.  \n*NOTE:* This must be done before making an instance.\n\nExample:\n\n```js\n// Android only\nOverflowAndroid.enable = navigator.userAgent.indexOf('Android') \u003e= 0;\n```\n\n```js\n// Anytime\nOverflowAndroid.enable = true;\n```\n\n### `OverflowAndroid.friction`\n\nDefault: `0.001`\n\nThis is strength of slowdown of inertia scroll after fast scroll operations. This is a number of pixels per milli second.\n\n### `OverflowAndroid.fps`\n\nDefault: `60`\n\nThis is frame rate of animation of inertia scroll after fast scroll operations. This is a number of frames per second.  \nThis is ignored when CSS Animations is used (see [`OverflowAndroid.transition`](#overflowandroidtransition)).\n\n### `OverflowAndroid.cursorScrollable`\n\nDefault: ![grab](grab.png)\n\nThe CSS `cursor` value when the target element is not receiving scroll operations.  \nIf `''` is specified, `cursor` is not changed.\n\n### `OverflowAndroid.cursorScrolling`\n\nDefault: ![grabbing](grabbing.png)\n\nThe CSS `cursor` value when the target element is receiving scroll operations.  \nIf `''` is specified, `cursor` is not changed.\n\n### `OverflowAndroid.scrollBar`\n\nDefault: `true`\n\nShow scroll bars.  \nNow, these scroll bars are mere **indicators** that only show each scroll-position, user can **not** scroll the element by operating these scroll bars.\n\n### `OverflowAndroid.scrollBarWidth`\n\nDefault: `5`\n\nSize of scroll bars. This is a number of pixels.\n\n### `OverflowAndroid.scrollBarColor`\n\nDefault: `'rgba(0,0,0,0.5)'`\n\nColor of scroll bars.\n\n### `OverflowAndroid.transition`\n\nIf `true` is specified to this option, the inertia scroll after fast scroll operations uses CSS Animations in modern browsers. The default is `false`.  \n*NOTE:* This must be done before making an instance.\n\nThe CSS Animations work smoothly in many browsers, but some browsers (particularly Firefox for Android) are not. I tried many ways (e.g. hardware acceleration), but I found nothing yet... *Someone, please let me know the way.* (But Firefox for Android can't scroll smoothly normal `overflow:scroll` in the first place.)\n\n## See Also\n\n[jQuery.overflowAndroid](https://github.com/anseki/jquery-overflow-android) is jQuery plugin that is wrapper of OverflowAndroid.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanseki%2Foverflow-android","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanseki%2Foverflow-android","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanseki%2Foverflow-android/lists"}