{"id":17096460,"url":"https://github.com/ramiel/caravaggio-react","last_synced_at":"2025-08-18T09:34:37.065Z","repository":{"id":47031848,"uuid":"280461642","full_name":"ramiel/caravaggio-react","owner":"ramiel","description":"React components to easily integrate Caravaggio (https://caravaggio.ramielcreations.com)","archived":false,"fork":false,"pushed_at":"2023-07-19T02:12:10.000Z","size":205,"stargazers_count":3,"open_issues_count":2,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-15T14:45:45.332Z","etag":null,"topics":["caravaggio","image","image-manipulation","image-processing","react","transformations"],"latest_commit_sha":null,"homepage":"https://caravaggio.ramielcreations.com/docs/nextjs","language":"TypeScript","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/ramiel.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2020-07-17T15:34:25.000Z","updated_at":"2022-03-24T10:40:56.000Z","dependencies_parsed_at":"2024-09-18T16:36:45.245Z","dependency_job_id":"4cc8f034-62a0-40a0-8cde-7cae6440a3ba","html_url":"https://github.com/ramiel/caravaggio-react","commit_stats":{"total_commits":50,"total_committers":3,"mean_commits":"16.666666666666668","dds":0.07999999999999996,"last_synced_commit":"4d5dab6bf52496975cb7f8ff0e17e36dbf329270"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramiel%2Fcaravaggio-react","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramiel%2Fcaravaggio-react/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramiel%2Fcaravaggio-react/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramiel%2Fcaravaggio-react/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ramiel","download_url":"https://codeload.github.com/ramiel/caravaggio-react/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239994002,"owners_count":19730780,"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":["caravaggio","image","image-manipulation","image-processing","react","transformations"],"created_at":"2024-10-14T14:45:45.222Z","updated_at":"2025-02-22T11:30:53.367Z","avatar_url":"https://github.com/ramiel.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# caravaggio-react\n\nThis library provides react components and hooks to integrate [Caravaggio](https://caravaggio.ramielcreations.com) in your react projects.\n\n## Install\n\nInstall with\n\n```bash\nyarn add caravaggio-react\n```\n\nor\n\n```bash\nnpm install caravaggio-react\n```\n\nThis library is entirelly written in `typescript`.\n\n## Caravaggio Provider\n\nAny component or hook in this library need to be descendant of a `CaravaggioProvider`. This provider will set which Caravaggio instance to use for transformations. Put this provider as on top as you can.\n\n```tsx\n// App.tsx  (or App.js)\n\nimport { CaravaggioProvider } from \"caravaggio-react\";\n\nexport default function App(props) {\n  return (\n    \u003cCaravaggioProvider\n      url=\"https://mycaravaggio.dev\"\n    \u003e\n      {props.children}\n    \u003c/CaravaggioProvider\u003e\n  );\n}\n```\n\nThe available props for the provider are\n\n| props   | description                                                                                                                                                               | optional/mandatory        |\n|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------|\n| url     | Tells the provider the url of Caravaggio instance\\. It can be an absolute of relative url in case Caravaggio is served from the same domain as your app                   | mandatory                 |\n| baseUrl | Caravaggio can only transform images with absolute url\\. If you want to use relative urls, set this value and all the images will be considered relative to this baseUrl  | optional, default \\`null` |\n\n\n## Image component\n\nAn image component is available to transform your images. It takes the same props as a normal `img` tag, plus an addotional `opt` props. You can pass any option available on [Caravaggio](https://caravaggio.ramielcreations.com).\n\n```tsx\nimport { Image } from 'caravaggio-react';\n\n\u003cImage\n  src=\"https://pexels.com/cangaroo.png\"\n  alt=\"A cangaroo jumping around\"\n  opt={{\n    o: \"webp\",\n    q: 90,\n    blur: 10,\n    rs: {\n      s: \"640x480\",\n    },\n  }}\n/\u003e\n```\n\nIn the above example we transform the image to `webp`, with a quality of `90`, a blur effect and resizing it to `640x480` pixels.\n\nCheck [Caravaggio documentation](https://caravaggio.ramielcreations.com) to know about all possible options.\n\n## Image srcset\n\nYou can generate a [`srcset`](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images) using the `ImageSet` component.\n\n\n```tsx\nimport { ImageSet } from \"caravaggio-react\";\n\n\u003cImageSet\n  src=\"https://img.com/butterfly.png\"\n  alt=\"A butterfly\"\n  className=\"myclass\"\n  // Sets is an array of sources\n  sets={[\n    {\n      // This source produce a webp image\n      type: \"image/webp\",\n      // The rules for this source\n      rules: {\n        // When screen is less wider than 300px\n        \"300w\": {\n          // Use this caravaggio options to produce the image\n          opt: {\n            o: \"webp\",\n            rs: {\n              s: \"300x\",\n            },\n          },\n        },\n        // Use this for screen large up to 600px\n        \"600w\": {\n          opt: {\n            o: \"webp\",\n            rs: {\n              s: \"600x\",\n            },\n          },\n        },\n      },\n    },\n    // This is the second set, we want it for browsers \n    // not capable of handling webp images.\n    // The rules are the same except for the output format\n    {\n      rules: {\n        \"300w\": {\n          opt: {\n            rs: {\n              s: \"300x\",\n            },\n          },\n        },\n        \"600w\": {\n          opt: {\n            rs: {\n              s: \"600x\",\n            },\n          },\n        },\n      },\n    },\n  ]}\n/\u003e;\n```\n\nThe component generates this html:\n\n```html\n\u003cfigure class=\"myclass\"\u003e\n  \u003cpicture\u003e\n    \u003csource\n      type=\"image/webp\"\n      srcset=\"\n        /api/assets/o:webp/rs,s:300x?image=http://localhost:3000/myimage.png 300w,\n        /api/assets/o:webp/rs,s:600x?image=http://localhost:3000/myimage.png 600w\n      \"\n    /\u003e\n    \u003csource\n      srcset=\"\n        /api/assets/rs,s:300x?image=http://localhost:3000/myimage.png 300w,\n        /api/assets/rs,s:600x?image=http://localhost:3000/myimage.png 600w\n      \"\n    /\u003e\n    \u003cimg src=\"/myimage.png\" alt=\"example image\" /\u003e\n  \u003c/picture\u003e\n\u003c/figure\u003e\n```\n\n## Hooks\n\n### useCaravaggio\n\nA hook, `useCaravaggio`, is provided to get, instead of an image tag, an image url with all the transformation applied. Very useful to insert images in css, or for css-in-js libraries\n\n```tsx\nimport { useCaravaggio } from \"caravaggio-react\";\n\nconst Component = () =\u003e {\n  const image = useCaravaggio(\"https://img.com/landscape.png\", {\n    blur: 0.3,\n  });\n\n  return \u003cdiv style={{ backgroundImage: `url('${image}')` }}\u003eSome content\u003c/div\u003e;\n};\n```\n\nThe first parameter is the image to transform, the second an object with all the transformations.\n\n### useCaravaggioIfAvailable\n\nSometimes you may not be sure if Caravaggio is available or not. This hook behaves exactly as `useCaravaggio` but\nis less sensible to problems: if Caravaggio provider is not available or the image is not defined, it returns a sensible default:\n\n```tsx\nimport { useCaravaggioIfAvailable } from \"caravaggio-react\";\n\nconst Component = ({image}: {image?: string}) =\u003e {\n  const image = useCaravaggioIfAvailable(image, {\n    blur: 0.3,\n  });\n\n  // If the image is not available returns null.\n  // If the provider is not available, returns the original image url\n\n  return \u003cdiv style={{ backgroundImage: `url('${image}')` }}\u003eSome content\u003c/div\u003e;\n};\n```\n\n### useCaravaggioBuilder\n\nThis hook return a function that can be invoked later to produce the image url\n\n```tsx\nimport { useCaravaggioIfAvailable } from \"caravaggio-react\";\n\nconst Component = ({image}: {image?: string}) =\u003e {\n  const builder = useCaravaggioBuilder();\n  const animals = [\n    {\n      name: 'tiger',\n      image: 'https://images.com/tiger.png'\n    },\n    {\n      name: 'monkey',\n      image: 'https://images.com/monkey.png'\n    },\n    {\n      name: 'horse',\n      image: 'https://images.com/horse.png'\n    }\n  ]\n\n  // If the image is not available returns null.\n  // If the provider is not available, returns the original image url\n\n  return \u003cdiv\u003e{\n    animals.map(animal =\u003e \u003cimg src={builder(animal.image, {o: 'jpg'})} key={animal.name} /\u003e)\n  }\u003c/div\u003e;\n};\n```\n\n## Available options\n\nTo know about all the options, check [Caravaggio documentation](https://caravaggio.ramielcreations.com).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Framiel%2Fcaravaggio-react","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Framiel%2Fcaravaggio-react","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Framiel%2Fcaravaggio-react/lists"}