{"id":14990211,"url":"https://github.com/ingmarh/scroll-shadow-element","last_synced_at":"2025-04-07T09:18:49.737Z","repository":{"id":45029003,"uuid":"303832103","full_name":"ingmarh/scroll-shadow-element","owner":"ingmarh","description":"Web component to enhance scrollable elements with dynamic scroll indicators.","archived":false,"fork":false,"pushed_at":"2024-12-05T23:11:58.000Z","size":5948,"stargazers_count":43,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-03-31T06:04:41.563Z","etag":null,"topics":["overflow-shadow","scroll","scroll-indicator","scroll-shadow","ui","web-component","webcomponent"],"latest_commit_sha":null,"homepage":"https://ingmarh.github.io/scroll-shadow-element/demo/","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/ingmarh.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","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":"2020-10-13T21:23:58.000Z","updated_at":"2025-02-11T04:42:13.000Z","dependencies_parsed_at":"2025-01-15T04:33:18.622Z","dependency_job_id":"f26f611d-7803-4429-9649-8b5928a3519f","html_url":"https://github.com/ingmarh/scroll-shadow-element","commit_stats":{"total_commits":75,"total_committers":1,"mean_commits":75.0,"dds":0.0,"last_synced_commit":"05f3f17ea568fb67aaba8144a171dac63e79e72a"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ingmarh%2Fscroll-shadow-element","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ingmarh%2Fscroll-shadow-element/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ingmarh%2Fscroll-shadow-element/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ingmarh%2Fscroll-shadow-element/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ingmarh","download_url":"https://codeload.github.com/ingmarh/scroll-shadow-element/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247622983,"owners_count":20968575,"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":["overflow-shadow","scroll","scroll-indicator","scroll-shadow","ui","web-component","webcomponent"],"created_at":"2024-09-24T14:19:42.908Z","updated_at":"2025-04-07T09:18:49.713Z","avatar_url":"https://github.com/ingmarh.png","language":"JavaScript","funding_links":[],"categories":["Design Elements"],"sub_categories":[],"readme":"# \u0026lt;scroll-shadow\u0026gt; element\n\n[![npm version][npm-version-badge-src]][npm-package-href]\n[![bundle size (minified and gzipped)][bundlesize-badge-src]][bundlesize-href]\n\nA small web component to enhance scrollable elements with dynamic scroll\nindicators.\n\n- Easy to use: Just wrap your element with `\u003cscroll-shadow\u003e`\n- Customizable scroll indicators\n- [See the demo][demo-href] 🔎\n\n## Installation\n\n```bash\nnpm install scroll-shadow-element\n```\n\nImport the module as part of your app bundle, or with a script tag.\n\n```js\nimport 'scroll-shadow-element'\n```\n\n```html\n\u003cscript type=\"module\" src=\"./node_modules/scroll-shadow-element/dist/index.js\"\u003e\u003c/script\u003e\n```\n\n\u003cdetails\u003e\u003csummary\u003eOr load from a CDN like unpkg\u003c/summary\u003e\n\n```html\n\u003c!-- unpkg CDN --\u003e\n\u003cscript type=\"module\" src=\"https://unpkg.com/scroll-shadow-element\"\u003e\u003c/script\u003e\n\n\u003c!-- Skypack CDN --\u003e\n\u003cscript type=\"module\" src=\"https://cdn.skypack.dev/scroll-shadow-element\"\u003e\u003c/script\u003e\n\n\u003c!-- Skypack CDN (minified) --\u003e\n\u003cscript type=\"module\" src=\"https://cdn.skypack.dev/scroll-shadow-element?min\"\u003e\u003c/script\u003e\n```\n\n\u003c/details\u003e\n\n## Usage\n\nWrap any element for dynamically added scroll indicators. For example:\n\n```html\n\u003cscroll-shadow\u003e\n  \u003cnav\u003eLong navigation…\u003c/nav\u003e\n\u003c/scroll-shadow\u003e\n```\n\n**Note**: When wrapping a non-scrollable `\u003ctable\u003e` element, then its first\n`\u003ctbody\u003e` will be used.\n\n## Configuration\n\nYou can change the default appearance with CSS.\n\n### Default\n\n```css\nscroll-shadow {\n  display: inline-block;\n  --scroll-shadow-size: 14;\n  --scroll-shadow-top: radial-gradient(farthest-side at 50% 0%, #0003, #0000);\n  --scroll-shadow-bottom: radial-gradient(farthest-side at 50% 100%, #0003, #0000);\n  --scroll-shadow-left: radial-gradient(farthest-side at 0%, #0003, #0000);\n  --scroll-shadow-right: radial-gradient(farthest-side at 100%, #0003, #0000);\n}\n```\n\n### Example: dark mode\n\n```css\n@media (prefers-color-scheme: dark) {\n  scroll-shadow {\n    --scroll-shadow-top: radial-gradient(farthest-side at 50% 0%, #fff3, #0000);\n    --scroll-shadow-bottom: radial-gradient(farthest-side at 50% 100%, #fff3, #0000);\n    --scroll-shadow-left: radial-gradient(farthest-side at 0%, #fff3, #0000);\n    --scroll-shadow-right: radial-gradient(farthest-side at 100%, #fff3, #0000);\n  }\n}\n```\n\n### CSS custom properties\n\n| Property               | Description                                            | Syntax            |\n| :--------------------- | :----------------------------------------------------- | :---------------- |\n| --scroll-shadow-size   | Sets the maximum size of the scroll indicators         | `\u003cinteger\u003e`       |\n| --scroll-shadow-top    | Controls the appearance of the top scroll indicator    | `none \\| \u003cimage\u003e` |\n| --scroll-shadow-bottom | Controls the appearance of the bottom scroll indicator | `none \\| \u003cimage\u003e` |\n| --scroll-shadow-left   | Controls the appearance of the left scroll indicator   | `none \\| \u003cimage\u003e` |\n| --scroll-shadow-right  | Controls the appearance of the right scroll indicator  | `none \\| \u003cimage\u003e` |\n\n## Browser support\n\n`scroll-shadow-element` works in all major browsers: all browsers that support\n[Custom Elements][custom-elementsv1], [Resize Observer][resizeobserver] and the\n[`min()` CSS function][css-math-functions] (Chrome/Edge 79+, Safari 13.1+, iOS\nSafari 13.4+, Firefox 75+). In older browsers, the element just won’t add\nscroll indicators.\n\nThe package is written with ES6 syntax. If you need to support older browsers,\nyou can configure your bundler to compile it to ES5 syntax.\n\n## Using with Jest\n\n```json\n{\n  \"jest\": {\n    \"moduleNameMapper\": {\n      \"^scroll-shadow-element$\": \"jest-transform-stub\"\n    }\n  }\n}\n```\n\n[Jest doesn’t fully support ES modules][jest-esm]: Depending on your\nconfiguration, you might see `SyntaxError: Unexpected token 'export'` along\nwith a few hints in the error output. Jest’s [\"moduleNameMapper\"\noption][jest-modulenamemapper] can be used to stub the module out. You can use\nany empty module, or [`jest-transform-stub`][jest-transform-stub].\n\n## Pure CSS alternative\n\n`\u003cscroll-shadow\u003e` is inspired by Lea Verou’s great [pure CSS scrolling shadows\ntechnique with `background-attachment: local`][pure-css-alternative].\n\nThe main motivation to create a custom element was to find a solution to have\nthe shadows above the content and independent of the element’s background. If\nyou don’t have these requirements, the pure CSS technique might work for you\ntoo.\n\nSince July 2023, it is possible to achieve the same with [CSS scroll-driven\nanimations][scroll-driven-animations] (see also [\"Proper\" Scrolling\nShadows][proper-scrolling-shadows] and [Scroll shadows with\nanimation-timeline][scroll-shadows-with-animation-timeline]). At the time of\nwriting, browser support for scroll-driven animations is limited: e.g. it won’t\nwork in Safari and Firefox. With `\u003cscroll-shadow\u003e`, scroll indicators can be\napplied declaratively in all major browsers, and the web component might get\nupdated in the future to use ScrollTimeline.\n\n## Development\n\n- `npm install` to install dependencies\n- `npm test -- --update-visual-baseline` to create local visual regression test baseline images\n- `npm test` to run tests\n- `npm run dev` to open a demo page for manual testing\n- `npm run lint` to run linting checks\n- `npm run lint:fix` to fix linting issues\n- `npm run build` to build\n\n## License\n\nDistributed under the terms of the MIT license. See [LICENSE](LICENSE) for details.\n\n[custom-elementsv1]: https://caniuse.com/custom-elementsv1\n[resizeobserver]: https://caniuse.com/resizeobserver\n[css-math-functions]: https://caniuse.com/css-math-functions\n[pure-css-alternative]: https://lea.verou.me/2012/04/background-attachment-local/\n[scroll-driven-animations]: https://developer.mozilla.org/docs/Web/CSS/CSS_scroll-driven_animations\n[proper-scrolling-shadows]: https://kizu.dev/scroll-driven-animations/#proper-scrolling-shadows\n[scroll-shadows-with-animation-timeline]: https://daverupert.com/2023/08/animation-timeline-scroll-shadows/\n[jest-esm]: https://jestjs.io/docs/ecmascript-modules\n[jest-modulenamemapper]: https://jestjs.io/docs/configuration#modulenamemapper-objectstring-string--arraystring\n[jest-transform-stub]: https://www.npmjs.com/package/jest-transform-stub\n[npm-version-badge-src]: https://img.shields.io/npm/v/scroll-shadow-element?style=flat-square\n[bundlesize-badge-src]: https://img.shields.io/bundlephobia/minzip/scroll-shadow-element?color=a8da93\u0026style=flat-square\n[npm-package-href]: https://npmjs.com/package/scroll-shadow-element\n[bundlesize-href]: https://bundlephobia.com/package/scroll-shadow-element\n[demo-href]: https://ingmarh.github.io/scroll-shadow-element/demo/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fingmarh%2Fscroll-shadow-element","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fingmarh%2Fscroll-shadow-element","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fingmarh%2Fscroll-shadow-element/lists"}