{"id":27158068,"url":"https://github.com/lindelwa122/image-slider","last_synced_at":"2026-07-12T02:31:54.502Z","repository":{"id":200499144,"uuid":"705522523","full_name":"lindelwa122/image-slider","owner":"lindelwa122","description":"A small JS library for creating image carousels.","archived":false,"fork":false,"pushed_at":"2023-10-17T08:30:19.000Z","size":219,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-26T10:39:20.348Z","etag":null,"topics":["image-carousel","image-slider","javascript","js-library","library"],"latest_commit_sha":null,"homepage":"","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/lindelwa122.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-10-16T07:18:44.000Z","updated_at":"2023-10-25T08:35:26.000Z","dependencies_parsed_at":null,"dependency_job_id":"ee97fe7f-2eaa-40f7-afa9-fcfff50eba12","html_url":"https://github.com/lindelwa122/image-slider","commit_stats":{"total_commits":18,"total_committers":2,"mean_commits":9.0,"dds":0.05555555555555558,"last_synced_commit":"bc2d19f38ec44c89c0e09eb7ea8f0d290c203cbf"},"previous_names":["lindelwa122/image-slider"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lindelwa122%2Fimage-slider","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lindelwa122%2Fimage-slider/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lindelwa122%2Fimage-slider/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lindelwa122%2Fimage-slider/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lindelwa122","download_url":"https://codeload.github.com/lindelwa122/image-slider/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247435041,"owners_count":20938530,"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":["image-carousel","image-slider","javascript","js-library","library"],"created_at":"2025-04-08T21:54:47.615Z","updated_at":"2025-10-23T16:40:50.218Z","avatar_url":"https://github.com/lindelwa122.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Image Slider \u0026middot; ![Dynamic JSON Badge](https://img.shields.io/badge/license-MIT-blue.svg) ![npm (scoped)](https://img.shields.io/npm/v/%40lindelwa122/image-slider) ![npm](https://img.shields.io/npm/dt/%40lindelwa122/image-slider) ![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)\n\n\u003cdiv align=\"center\"\u003e\n\u003cp\u003eA small JS library for creating image carousels.\u003c/p\u003e\n\n![Dropdown Menu Preview](./src/images/image-carousel-preview.png)\n\n\u003cdiv\u003e\n    \u003ca href=\"https://npm.runkit.com/%40lindelwa122%2Fimage-slider\"\u003eTry on RunKit\u003c/a\u003e\n    \u0026middot;\n    \u003ca href=\"https://github.com/lindelwa122/image-slider/issues\"\u003eReport Bugs\u003c/a\u003e\n    \u0026middot;\n    \u003ca href=\"https://github.com/lindelwa122/image-slider/issues\"\u003eRequest Feature\u003c/a\u003e\n\u003c/div\u003e\n\n\u003c/div\u003e\n\n## About the Project\n\nThe Image Slider library provides a user-friendly solution for creating highly customizable image carousels that seamlessly integrate with a wide range of projects. Its flexibility allows for easy configuration, making it a versatile choice for various scenarios.\n\n## Installation\n\nInstall using NPM:\n\n```\nnpm install @lindelwa122/image-slider\n```\n\n## Usage\n\n### Creating a Slider\n\nCreating a customized image carousel with the Image Slider library is a straightforward process. Begin by implementing the slider as shown below:\n\n```javascript\nimport imageSlider from '@lindelwa122/image-slider';\nimport image1 from './images/image-1.png';\nimport image2 from './images/image-2.png';\n\nconst slider = imageSlider(\n  '350px',\n  '450px',\n  { src: 'https://unsplash/image.png', alt: '' },\n  { src: image1, alt: '' },\n  { src: image2, alt: '' },\n);\n```\n\nIn this example, the `imageSlider` function is invoked by providing the desired height and width for the carousel container, followed by the images to be used in the carousel. The images can be specified using various formats, including URLs or local paths.\n\n### Creating a Square Container\n\nYou can achieve a square carousel container by providing either the height or width while invoking `imageSlider`. If neither is provided, an error will be thrown. This feature is handy for creating responsive square containers. Here's an example:\n\n```javascript\nimport imageSlider from '@lindelwa122/image-slider';\nimport image1 from './images/image-1.png';\nimport image2 from './images/image-2.png';\n\nconst slider = imageSlider(\n  undefined,\n  '30%',\n  { src: 'https://unsplash/image.png', alt: '' },\n  { src: image1, alt: '' },\n  { src: image2, alt: '' },\n);\n```\n\nIn the example above, the width is set to 30% while the height is set to `undefined`. This will create a square container that's responsive to the page, with the height and width being equal.\n\nYou can also set the width to `undefined` and define the height as needed, achieving the same square container result.\n\nSetting both height and width to `undefined` will make the carousel container take up 100% of the parent container's width, and the height will adjust based on the images. The carousel container behaves as a `block` element in this scenario.\n\n### Image Format\n\nFor the image to be properly recognized, it should be in the following format: `{ src: 'https://unsplash/image.png', alt: ''}`. If the `src` key is not found in the provided `object` or if an item in the `images` array is not an object, an error will be thrown. While `alt` is not a mandatory field, it is highly recommended you provide it for improved accessibility.\n\n### Updating Configurations\n\nThe `imageSlider` module comes with default configurations that define its behavior. These configurations can be easily updated to tailor the image slider to your specific project requirements.\n\nThe default configurations are as follows:\n\n```javascript\n{\n    animation: true,\n    animationDuration: 500,\n    imageFit: 'cover',\n    showCounter: true,\n    showControls: true,\n    showDots: true,\n}\n```\n\n- **animation**: A boolean indicating whether to enable animation.\n- **animationDuration**: The duration of the animation in milliseconds.\n- **imageFit**: The image fit mode, using values such as 'cover', 'contain', 'fill', or 'none'.\n- **showCounter**: A boolean indicating whether to display the image counter.\n- **showControls**: A boolean indicating whether to display navigation controls.\n- **showDots**: A boolean indicating whether to display navigation dots.\n\nTo update configurations, simply provide an object with the configurations you wish to change, like this:\n\n```javascript\nslider.updateConfig({ animation: false, imageFit: 'contain' });\n```\n\nIn this example, animation is disabled and the image fitting is set to 'contain'.\n\nNote that most configurations are boolean values, except for `animationDuration` (number) and `imageFit` (string). The `imageFit` uses values such as 'cover', 'contain', 'fill', or 'none' based on the CSS `object-fit` property.\n\n### Automatically Advancing Slides\n\nYou can set up the image slider to automatically advance the slides at a specified interval using the `auto` function:\n\n```javascript\nslider.auto(2000);\n```\n\nThe `auto` function takes a parameter `ms` (milliseconds), indicating the time interval between slide transitions. By default, the interval is set to 1000 milliseconds (1 second). The function returns an interval ID, which can be used with `clearInterval` to stop the automatic slide transitions at any time:\n\n```javascript\nconst intervalId = slider.auto(2000); // Start auto-advancing every 2 seconds\n\n// Stop auto-advancing after 10 seconds\nsetTimeout(() =\u003e {\n  clearInterval(intervalId);\n}, 10000);\n```\n\nIn this example, the slider will automatically transition to the next image every 2 seconds. After 10 seconds, we use `clearInterval` to stop the automatic advancement.\n\nThis feature is useful when you want to create a self-advancing image carousel without requiring user interaction.\n\n### Adding the Image Slider to a Page\n\nTo display the image slider on a web page, you can use the `append` function provided by the image slider module. This function appends the slider to a specified parent element based on a selector.\n\nHere's how you can use `append` to display the image slider:\n\n```javascript\nslider.append('#root');\n```\n\nIn this example, the image slider will be appended to the element with the ID `root`. Make sure that the specified selector corresponds to an existing element in your HTML, or an error will be thrown.\n\nThis function simplifies integrating the image slider into your web page, allowing for easy and seamless display of the image carousel.\n\n## Examples\n\n### Full Example: Using Image Slider Library\n\nHere's a complete example demonstrating how to use the Image Slider library:\n\n```javascript\nimport imageSlider from '@lindelwa122/image-slider';\nimport image1 from './images/image-1.png';\nimport image2 from './images/image-2.png';\n\nconst slider = imageSlider(\n  '350px',\n  '450px',\n  { src: image1, alt: 'Cat climbing a tree' },\n  { src: image2, alt: 'Dog sleeping under a tree' },\n);\n\n// Automatically advance the slide every 2 seconds\nslider.auto(2000);\n\n// Update the image fit to 'contain'\nslider.updateConfig({ imageFit: 'contain' });\n\n// Append the slider to an element with ID 'root'\nslider.append('#root');\n```\n\n### Slideshow Example: Using Image Slider as a Slideshow\n\nYou can use the Image Slider to create a slideshow and disable control options. Here's an example:\n\n```javascript\nimport imageSlider from '@lindelwa122/image-slider';\nimport image1 from './images/image-1.png';\nimport image2 from './images/image-2.png';\n\nconst slider = imageSlider(\n  '350px',\n  '450px',\n  { src: image1, alt: 'Cat climbing a tree' },\n  { src: image2, alt: 'Dog sleeping under a tree' },\n);\n\n// Automatically advance the slide every 5 seconds\nslider.auto(5000);\n\n// Update configurations to hide controls, dots, and counter\nslider.updateConfig({\n  showCounter: false,\n  showControls: false,\n  showDots: false,\n});\n\n// Append the slider to an element with ID 'root'\nslider.append('#root');\n```\n\nIn this example, the images will automatically update every 5 seconds, and the user won't have control over manual image changes since controls, dots, and the counter are hidden.\n\n## Contributing\n\nContributions are welcome, if you have any ideas of how can we make this project better please create an [issue](https://github.com/lindelwa122/image-slider/issues).\n\n## Contact\n\n- GitHub: https://github.com/lindelwa122\n- Email: nqabenhlemlaba22@gmail.com\n- Instagram: [https://instagram.com/q.codes\\_\\_](https://instagram.com/q.codes__)\n\n## Acknowledgements\n\n- Project inspired by [The Odin Project's](https://theodinproject.com) exercise.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flindelwa122%2Fimage-slider","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flindelwa122%2Fimage-slider","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flindelwa122%2Fimage-slider/lists"}