{"id":19511149,"url":"https://github.com/littlee/canvas-sprite","last_synced_at":"2025-04-26T03:32:28.239Z","repository":{"id":33143133,"uuid":"153051057","full_name":"littlee/canvas-sprite","owner":"littlee","description":"Render sprite animation with canvas, (0 dependencies)","archived":false,"fork":false,"pushed_at":"2023-01-06T01:36:28.000Z","size":3261,"stargazers_count":2,"open_issues_count":20,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-11T20:05:55.181Z","etag":null,"topics":["animation","canvas","sprite","spritesheet"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/littlee.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-10-15T04:00:56.000Z","updated_at":"2023-04-25T05:53:42.000Z","dependencies_parsed_at":"2023-01-14T23:35:38.595Z","dependency_job_id":null,"html_url":"https://github.com/littlee/canvas-sprite","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/littlee%2Fcanvas-sprite","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/littlee%2Fcanvas-sprite/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/littlee%2Fcanvas-sprite/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/littlee%2Fcanvas-sprite/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/littlee","download_url":"https://codeload.github.com/littlee/canvas-sprite/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250288621,"owners_count":21405831,"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":["animation","canvas","sprite","spritesheet"],"created_at":"2024-11-10T23:19:35.951Z","updated_at":"2025-04-26T03:32:27.429Z","avatar_url":"https://github.com/littlee.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# canvas-sprite\n\nRender sprite animation with canvas\n\ndemo: https://codesandbox.io/s/red-dawn-m706x\n\n## Why?\n\nBecause why not ?\n\nEven simple sprite sheet animation can be done with pure CSS, but:\n\n- the animation looks \"shaking\" on Android device when the element is using repsonsive unit in some case.\n- the animation looks \"flashing\" on iOS device when the sprite image's dimension is too large.\n\n## Install!\n\n```\nnpm i -S canvas-sprite\n```\n\nor you can include `dist/main.js` with a `\u003cscript /\u003e` tag, it exposes `CanvasSprite` to global\n\n## Usage!\n\n### Simple Case\n\n```js\nimport CanvasSprite from 'canvas-sprite';\n\nvar cs = CanvasSprite({\n  canvas: document.getElementById('canvas'),\n  imageUrl: './sprite.png',\n  frames: 25,\n  fps: 12,\n  loop: true,\n  onLoop: function (count) {\n    console.log('have looped', count, 'times');\n  },\n  onEnd: function () {\n    console.log('end');\n  }\n});\n\n// call destroy when the canvas element is removed from DOM\ncs.destroy();\n```\n\n### Cache Management\n\nIf an url string is passed to `options.imageUrl`, the library has to fetch the image from the URL before display the animation, and when the image is too large, it may take too long to fetching it, this will be the case when trying to switch sprite sheet on the same canvas element. So we can pass a loaded `Image` to `options.imageUrl` to get a seamlessly switching.\n\n```js\nimport CanvasSprite, { loadImage } from 'canvas-sprite';\n\nlet cs = null;\nfunction createAnim(image) {\n  cs.destroy();\n  cs = CanvasSprite({\n    canvas: document.getElementById('canvas'),\n    imageUrl: image,\n    frames: 25,\n    fps: 12,\n    loop: true\n  });\n}\n\n// prepare image cache\nlet cache = [];\nPromise.all([\n  loadImage('./sprite_sheet_1.png'),\n  loadImage('./sprite_sheet_2.png')\n])\n  .then(imgs =\u003e {\n    cache = imgs;\n    console.log('cache is ready');\n  })\n  .then(() =\u003e {\n    createAnim(cache[0]);\n    // some time later...\n    setTimeout(() =\u003e {\n      createAnim(cache[1]);\n    }, 10 * 1000);\n  });\n```\n\n## API!\n\noptions:\n\n- canvas (HTMLCanvasElement): the canvas we want to render the sprite, **required**\n- imageUrl (String|Image): the sprite image url or image element, **required**\n- frames (Number): the number of sprite frames, **required**\n- fps (Number): frames rendered per second, **required**\n- loop (Boolean): should sprite animation loop, default to `true`\n- onEnd (Function): function invoked when animation ends if options.loop is `false`\n- onLoop (Function): function invoked every time aniamtion loops if options.loop is `true`\n\ninstance methods:\n\n- play(): play animation, can be called after pause/stop\n- pause(): pause animation, stay in curren frame\n- stop(): stop animation, reset to first frame\n- destroy(): destroy animation, should be called when canvas element is removed(unmounted) from DOM, in case of memory leak\n\nstatic methods:\n\n- loadImage(url): load image from url, return a Promise which resolve the loaded image\n\n## Migrate from v1.x\n\nBasically nothing, `width` and `height` are removed from options since they can be calculated, automagically.\n\n## Caveats\n\n- we support single row sprite image only for now\n- make sure the width \u0026 height of every frame is integer for performance boost\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flittlee%2Fcanvas-sprite","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flittlee%2Fcanvas-sprite","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flittlee%2Fcanvas-sprite/lists"}