{"id":13815840,"url":"https://github.com/bpierre/loot-rarity","last_synced_at":"2025-06-14T18:11:11.130Z","repository":{"id":47199262,"uuid":"400934276","full_name":"bpierre/loot-rarity","owner":"bpierre","description":"🤍 💚 💙 💜 🧡 ❤️ Rarity levels for Loot.","archived":false,"fork":false,"pushed_at":"2021-09-09T11:59:55.000Z","size":606,"stargazers_count":455,"open_issues_count":1,"forks_count":51,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-06-13T10:56:11.324Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://loot-rarity.bpier.re/","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/bpierre.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":"2021-08-29T02:37:30.000Z","updated_at":"2025-04-13T11:06:05.000Z","dependencies_parsed_at":"2022-09-14T22:40:24.120Z","dependency_job_id":null,"html_url":"https://github.com/bpierre/loot-rarity","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/bpierre/loot-rarity","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bpierre%2Floot-rarity","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bpierre%2Floot-rarity/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bpierre%2Floot-rarity/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bpierre%2Floot-rarity/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bpierre","download_url":"https://codeload.github.com/bpierre/loot-rarity/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bpierre%2Floot-rarity/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259860438,"owners_count":22922990,"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":[],"created_at":"2024-08-04T04:04:13.236Z","updated_at":"2025-06-14T18:11:11.092Z","avatar_url":"https://github.com/bpierre.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"\u003cimg width=\"1280\" alt=\"Loot Rarity\" src=\"https://user-images.githubusercontent.com/36158/131556816-cf5861c7-8619-4b56-9d90-f538ebb86f74.png\"\u003e\n\n[![npm version](https://badgen.net/npm/v/loot-rarity)](https://www.npmjs.com/package/loot-rarity) [![bundle size](https://badgen.net/bundlephobia/minzip/loot-rarity)](https://bundlephobia.com/result?p=loot-rarity) [![License](https://badgen.net/github/license/bpierre/loot-rarity)](https://github.com/bpierre/loot-rarity/blob/main/LICENSE)\n\nRarity levels for [Loot](https://lootproject.com).\n\n## How are the rarity levels determined?\n\nThe rarity level of any given item is deducted from its number of occurrences in the total number of Loot items.\n\n| Rarity level                                                                                                                             | Description                                        |           Occurrences |\n| ---------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------- | --------------------: |\n| \u003cimg width=\"10\" alt=\"\" src=\"https://user-images.githubusercontent.com/36158/131379065-5eef7b05-458c-4717-bfa8-c2d086283f0b.png\"\u003e Level 1 | **Common** items appear **375** or more times.     | 47.25% - 30,237 items |\n| \u003cimg width=\"10\" alt=\"\" src=\"https://user-images.githubusercontent.com/36158/131379064-442c9a9e-90c9-4cb9-8fac-1ed0dbed5609.png\"\u003e Level 2 | **Uncommon** items appear less than **375** times. |  12.61% - 8,073 items |\n| \u003cimg width=\"10\" alt=\"\" src=\"https://user-images.githubusercontent.com/36158/131379063-1b6fa149-945f-467a-893e-e90eab48c20c.png\"\u003e Level 3 | **Rare** items appear less than **358** times.     |  11.78% - 7,537 items |\n| \u003cimg width=\"10\" alt=\"\" src=\"https://user-images.githubusercontent.com/36158/131379062-4847e475-8250-4e17-bec1-71c586b4e419.png\"\u003e Level 4 | **Epic** items appear less than **101** times.     |  10.29% - 6,587 items |\n| \u003cimg width=\"10\" alt=\"\" src=\"https://user-images.githubusercontent.com/36158/131379061-acead0af-797b-47f9-9d71-db8c7d6b1696.png\"\u003e Level 5 | **Legendary** items appear less than **10** times. |   9.67% - 6,189 items |\n| \u003cimg width=\"10\" alt=\"\" src=\"https://user-images.githubusercontent.com/36158/131379060-7fa91e93-dbc2-4a55-8d0c-125bc43e16e1.png\"\u003e Level 6 | **Mythic** items appear exactly **1** time.        |    8.4% - 5,377 items |\n\n## Installation\n\n```sh\nnpm i --save loot-rarity # npm\nyarn add loot-rarity # yarn\npnpm add loot-rarity # pnpm\n```\n\n## API\n\n### Types\n\n```ts\n// RarityLevel goes from 1 (common) to 6 (mythic). See table above for more info.\ntype RarityLevel = 1 | 2 | 3 | 4 | 5 | 6;\n\n// ColorFn allows to override a color in different places.\ntype ColorFn = (colorParameters: {\n  level: RarityLevel; // the rarity level\n  color: string; // the base color you can override\n  itemName?: string; // in certain cases the item name will be present\n}) =\u003e string | void | null; // return a string to override the color\n```\n\n### itemRarity()\n\n```ts\nfunction itemRarity(itemName: string): RarityLevel;\n```\n\nThis function returns the rarity level of an item, given its name.\n\nExample:\n\n```js\nlet rarity = itemRarity('\"Golem Roar\" Studded Leather Belt of Fury');\n\nconsole.log(rarity); // 6\n```\n\n### lootRarity()\n\n```ts\nfunction lootRarity(items: string): RarityLevel;\n```\n\nThis function returns the rarity level of a Loot from the 8 items it contains.\n\nExample:\n\n```js\nlet items = [\n  \"Warhammer of the Fox\",\n  \"Studded Leather Armor\",\n  \"Demon Crown\",\n  \"Sash\",\n  \"Studded Leather Boots of Power\",\n  \"Silk Gloves\",\n  \"Necklace of Power\",\n  \"Silver Ring\",\n];\n\nlet rarity = lootRarity(items);\n\nconsole.log(rarity); // 3\n```\n\n### rarityColor()\n\n```ts\nfunction rarityColor(\n  itemOrRarityLevel: string | RarityLevel,\n  options?: { colorFn: ColorFn }\n): string;\n```\n\nThis function returns the color of a rarity level, given an item name or a rarity level.\n\nExample:\n\n```js\nlet color = rarityColor(\"Ornate Belt of Perfection\");\n\nconsole.log(color); // \"#c13cff\"\n```\n\n### rarityDescription()\n\n```ts\nfunction rarityDescription(itemOrRarityLevel: string | RarityLevel): string;\n```\n\nThis function returns the description of a rarity level, given an item name or a rarity level.\n\nExample:\n\n```js\nlet levelA = rarityDescription(1);\nlet levelB = rarityDescription(\"Studded Leather Boots of Rage\");\n\nconsole.log(levelA); // \"Common\"\nconsole.log(levelB); // \"Legendary\"\n```\n\n### rarityImage()\n\n```ts\nfunction rarityImage(\n  imageOrItems: string | string[],\n  options?: {\n    colorFn?: ColorFn;\n    displayItemLevels?: Boolean;\n    displayLootLevel?: Boolean;\n    imageFormat: \"data-uri\" | \"svg\";\n  }\n): Promise\u003cstring\u003e;\n```\n\nThis function generates an image with added rarity levels.\n\nIt accepts any of the following:\n\n- SVG source of a Loot image.\n- An array of Loot items.\n- Data URI representing a Loot image.\n- Data URI representing a Loot metadata (as returned by the `tokenURI()` method of the Loot contract).\n- HTTP URL pointing to a Loot image.\n\nOptions:\n\n- `colorFn` allows to override the color of a particular item.\n- `displayItemLevels` allows to add levels to the items list.\n- `displayLootLevel` allows to display the Loot level badge.\n- `imageFormat` controls the output: data URI (`\"data-uri\"`) (default) or SVG source (`\"svg\"`).\n\nExample with React, [use-nft](https://github.com/spectrexyz/use-nft) to load the image, and [swr](https://github.com/vercel/swr) to handle the async function:\n\n```jsx\nimport { rarityImage } from \"loot-rarity\";\nimport { useNft } from \"use-nft\";\nimport useSWR from \"swr\";\n\nfunction Loot({ tokenId }) {\n  const { nft } = useNft(LOOT, id);\n  const { data: image } = useSWR(nft?.image, rarityImage);\n  return image ? \u003cimg src={image} /\u003e : \u003cdiv\u003eLoading…\u003c/div\u003e;\n}\n```\n\nThe resulting images could look like this:\n\n#### Default\n\n```js\nlet image = await rarityImage(image);\n```\n\n\u003cimg width=\"1000\" alt=\"Illustration of how rarityImage() transforms Loot images.\" src=\"https://user-images.githubusercontent.com/36158/132146191-3a0c6426-b33e-4a22-a1d8-3620d993e1e7.png\"\u003e\n\n#### With the rarity levels displayed\n\n```js\nlet rarified = await rarityImage(image, { displayItemLevels: true });\n```\n\n\u003cimg width=\"1000\" alt=\"Illustration of how rarityImage() transforms Loot images with the rarity levels added.\" src=\"https://user-images.githubusercontent.com/36158/132146189-52b0b1cd-0509-4ebc-a7f9-2a0a9b0ea16e.png\"\u003e\n\n#### With custom colors\n\n```js\nlet rarified = await rarityImage(image, {\n  colorFn: ({ itemName }) =\u003e itemName?.includes(\"Slippers\") \u0026\u0026 \"cyan\",\n});\n```\n\n\u003cimg width=\"1000\" alt=\"Illustration of how rarityImage() transforms Loot images with custom colors.\" src=\"https://user-images.githubusercontent.com/36158/132146190-9ce0f17a-364e-4ca0-b1a9-9326eb5f2cca.png\"\u003e\n\n#### With the Loot level\n\n```js\nlet rarified = await rarityImage(image, { displayLootLevel: true });\n```\n\n\u003cimg width=\"1000\" alt=\"Illustration of how rarityImage() transforms Loot images with the Loot level badge.\" src=\"https://user-images.githubusercontent.com/36158/132579918-9005d51a-d702-4e08-9c66-01db5e2004d6.png\"\u003e\n\n### rarityImageFromItems()\n\n```ts\nfunction rarityImageFromItems(\n  items: string[],\n  options: {\n    colorFn?: ColorFn;\n    displayItemLevels?: Boolean;\n    displayLootLevel?: Boolean;\n    imageFormat: \"data-uri\" | \"svg\";\n  }\n): string;\n```\n\nThis function is similar to rarityImage, except it only accepts an array of items. It is useful when you already have a list of items, because it returns a `string` directly (while `rarityImage()` returns a `Promise` resolving to a `string`).\n\nOptions:\n\n- `colorFn` allows to override the color of a particular item.\n- `displayItemLevels` allows to add levels to the items list.\n- `displayLootLevel` allows to display the Loot level badge.\n- `imageFormat` controls the output: data URI (`\"data-uri\"`) (default) or SVG source (`\"svg\"`).\n\nExample:\n\n```js\nimport { rarityImageFromItems } from \"loot-rarity\";\n\nconst bag = [\n  \"Grimoire\",\n  '\"Woe Bite\" Ornate Chestplate of the Fox +1',\n  \"Silk Hood\",\n  \"Heavy Belt of Fury\",\n  \"Shoes\",\n  \"Silk Gloves\",\n  '\"Rune Glow\" Amulet of Rage',\n  \"Silver Ring\",\n];\n\ndocument.body.innerHTML = `\n  \u003cimg src=${rarityImageFromItems(bag)} /\u003e\n`;\n```\n\n## Demo app\n\nHave a look at [the demo app](https://loot-rarity.vercel.app/) to see how it works.\n\nYou can also run it from this repository (see [`demo/`](./demo/)):\n\n```sh\n# Install pnpm if needed\nnpm i -g pnpm\n\n# Build loot-rarity\npnpm i\npnpm build\n\n# Run the demo app\ncd demo\npnpm i\npnpm dev\n```\n\n## Thanks\n\n- [@scotato](https://github.com/scotato) for [github.com/scotato/inventory](https://github.com/scotato/inventory), loot-rarity was heavily inspired by it.\n- [@Anish-Agnihotri](https://github.com/Anish-Agnihotri) for [the data](https://github.com/Anish-Agnihotri/dhof-loot) he extracted from Loot and that loot-rarity is using.\n\n## License\n\n[MIT](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbpierre%2Floot-rarity","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbpierre%2Floot-rarity","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbpierre%2Floot-rarity/lists"}