{"id":14384384,"url":"https://github.com/laurentpayot/minidenticons","last_synced_at":"2025-05-16T06:05:23.740Z","repository":{"id":39600599,"uuid":"348259443","full_name":"laurentpayot/minidenticons","owner":"laurentpayot","description":"Super lightweight SVG identicon (pixelated avatar) generator","archived":false,"fork":false,"pushed_at":"2024-05-30T07:43:40.000Z","size":295,"stargazers_count":500,"open_issues_count":1,"forks_count":26,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-08T15:14:41.000Z","etag":null,"topics":["avatar","avatar-component","avatar-generator","avatars","gdpr","identicon","identicon-generator","identicon-generators","identicon-github","identicon-library","identicon-svgs","identicons","javascript","light","lightweight","profile-picture","profile-picture-generator","svg","tiny","typescript"],"latest_commit_sha":null,"homepage":"https://laurentpayot.github.io/minidenticons","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/laurentpayot.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":"2021-03-16T07:55:04.000Z","updated_at":"2025-04-06T21:57:03.000Z","dependencies_parsed_at":"2024-06-18T16:50:27.127Z","dependency_job_id":null,"html_url":"https://github.com/laurentpayot/minidenticons","commit_stats":{"total_commits":195,"total_committers":2,"mean_commits":97.5,"dds":0.00512820512820511,"last_synced_commit":"ebf03a5401dbc84966309ae0f51db2dae63a0955"},"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laurentpayot%2Fminidenticons","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laurentpayot%2Fminidenticons/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laurentpayot%2Fminidenticons/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laurentpayot%2Fminidenticons/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/laurentpayot","download_url":"https://codeload.github.com/laurentpayot/minidenticons/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254478187,"owners_count":22077676,"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":["avatar","avatar-component","avatar-generator","avatars","gdpr","identicon","identicon-generator","identicon-generators","identicon-github","identicon-library","identicon-svgs","identicons","javascript","light","lightweight","profile-picture","profile-picture-generator","svg","tiny","typescript"],"created_at":"2024-08-28T18:01:20.787Z","updated_at":"2025-05-16T06:05:23.722Z","avatar_url":"https://github.com/laurentpayot.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# Minidenticons\n\nSuper lightweight SVG identicon generator. No dependencies.\n\n![minified + brotlied size](https://badgen.net/static/minified%20brotli/269%20bytes/green)\n![minified + zipped size](https://badgen.net/static/minified%20zip/311%20bytes/green)\n\u003csup\u003e(using the `minidenticon()` function only)\u003c/sup\u003e\n\n![minified + brotlied size](https://badgen.net/static/minified%20brotli/453%20bytes/green)\n![minified + zipped size](https://badgen.net/static/minified%20zip/552%20bytes/green)\n\u003csup\u003e(using the included custom element)\u003c/sup\u003e\n\n\u003c!--\n[![dependencies](https://badgen.net/bundlephobia/dependency-count/minidenticons)](https://bundlephobia.com/package/minidenticons)\n--\u003e\n[![dependencies](https://badgen.net/static/dependencies/None/green)](https://github.com/laurentpayot/minidenticons/blob/main/package.json#L60)\n[![types](https://badgen.net/npm/types/minidenticons)](https://github.com/laurentpayot/minidenticons/blob/main/index.d.ts)\n[![npm](https://badgen.net/npm/v/minidenticons)](https://www.npmjs.com/package/minidenticons)\n[![license](https://badgen.net/github/license/laurentpayot/minidenticons)](https://github.com/laurentpayot/minidenticons/blob/main/LICENSE)\n\n[\u003cimg src=\"img/minidenticons.svg\" style=\"width:100%\" alt=\"Minidenticons\"\u003e](https://laurentpayot.github.io/minidenticons/)\n\n## Why\n\n- Generate identicons (pixelated avatars) on the client from usernames instead of fetching images from a server. Much faster, saves bandwidth and [GDPR compliant](https://gdpr.eu/eu-gdpr-personal-data/).\n- Replace dull initial avatars like \u003csub\u003e\u003cimg src=\"img/initials.svg\" alt=\"laurent identicon\" width=\"24\" height=\"24\"\u003e\u003c/sub\u003e by easily remembered graphical avatars.\n- Give a visual representation of hashes or any ID string.\n\n## Live Demo :video_game:\n\nPlay with it [here](https://laurentpayot.github.io/minidenticons/).\n\n## Basic usage with the included custom element\n\nMinidenticons uses [ES modules](https://jakearchibald.com/2017/es-modules-in-browsers/), now [widely supported](https://caniuse.com/es6-module) in browsers. Import the `minidenticonSvg` custom element from the `minidenticons.min.js` file. This file can be located in a CDN (example below) or copied in any directory of your website (for better performance and to be GDPR compliant, since you don’t have to connect to a third party server).\n\n```html\n\u003cscript type=\"module\"\u003e\n  import { minidenticonSvg } from 'https://cdn.jsdelivr.net/npm/minidenticons@4.2.1/minidenticons.min.js'\n\u003c/script\u003e\n```\n\nThen simply use `minidenticon-svg` tags with a `username` attribute :joy:\n\n```html\n\u003cminidenticon-svg username=\"laurent\"\u003e\u003c/minidenticon-svg\u003e\n```\n\u003csup\u003e(Note that like for all elements except [void elements](https://html.spec.whatwg.org/multipage/syntax.html#void-elements), the closing tag `\u003c/minidenticon-svg\u003e` is required)\u003c/sup\u003e\n\nFor instance with the `laurent` username you will get the following identicon (without the border):\n\u003ctable\u003e\u003ctr\u003e\u003ctd\u003e\n\u003cimg src=\"img/laurent.svg\" alt=\"laurent identicon\" width=\"120\" height=\"120\"\u003e\n\u003c/td\u003e\u003c/tr\u003e\u003c/table\u003e\n\n### Styling\n\nFor easy CSS styling:\n\n- Minidenticons are [SVG](https://en.wikipedia.org/wiki/SVG) images that will take [all the space available.](https://raw.githubusercontent.com/laurentpayot/minidenticons/main/img/laurent.svg) The picture above is resized.\n\n- The background is transparent.\n- There is white space around the colored square matrix to allow uncropped circle avatars.\n\nSo with the following CSS:\n```css\nminidenticon-svg svg {\n  border-radius: 50%;\n  background-color: grey;\n  height: 48px;\n  width: 48px;\n};\n```\nYou will get:\n\n![Styled minidenticon](img/laurent-round.svg)\n\n\nBy default the color saturation is set to 95% and the lightness is set to 45%. But you can change these values with the `saturation` and/or `lightness` attributes, for instance:\n\n```html\n\u003cminidenticon-svg username=\"laurent\" saturation=\"60\" lightness=\"50\"\u003e\u003c/minidenticon-svg\u003e\n```\n\nPlay with [the demo](https://laurentpayot.github.io/minidenticons/) to find a combination of saturation and lightness that matches your website theme colors: light, dark or whatever :sunglasses:\n\n![Minidenticons light](img/smileys-white.svg)\n![Minidenticons dark](img/smileys-black.svg)\n![Minidenticons weird](img/smileys-yellow.svg)\n\n### Performance\n\n- *Custom element* identicons are [memoized](https://en.wikipedia.org/wiki/Memoization) (stored in memory so that it does not need to be recalculated).\n- To see how long it takes for your browser to generate 100 identicon custom elements (for a big page) try out the [online browser benchmark](https://laurentpayot.github.io/minidenticons/benchmark/browser.html).\n\n## Advanced usage with the `minidenticon()` function\n\nInstead of using the custom element, you can also use the `minidenticon()` function to generate SVG strings in your client (or your server).\n\n```typescript\nminidenticon(seed: string, saturation?: number|string, lightness?: number|string, hashFn?: (str: string) =\u003e number): string\n```\n\nThe `minidenticon()` function will return a SVG string generated from its seed string argument. The seed argument can be a username, but actually any string used as an identifier.\n\nOptional saturation and lightness arguments should be percentages; that is, numbers (or strings) between 0 and 100.\n\nIf you need to, you can use your own hash function as argument of the fourth parameter (optional). Your custom hash function must take a string and return a number. The last 15 bits of the integer part of the hash will be used to draw the squares. The included custom element does not use this last parameter.\n\nNote that the `minidenticon()` function itself is *not* memoized.\n\n### NodeJS\n\nBe sure to use a NodeJS version greater or equal to **15.14.0**.\n\n#### Installation\n\n```bash\nnpm install minidenticons\n```\n\n#### Import\n\n```javascript\nimport { minidenticon } from 'minidenticons'\n```\n\nThe `minidenticonSvg` custom element should be tree-shaken from your bundle, for an even smaller size of minidenticons :grin:\n\n#### Performance\n\nThe `minidenticon()` function is *fast*. You can see by yourself if you run `node benchmark/node` at the root of a Minidenticons git clone. On my machine I get the following result:\n\n```\nTime to generate 10000 minidenticon SVG strings for 15 characters random seeds:\n8 milliseconds (10 runs average)\n```\n### React\n\nThe following [React component example](https://codepen.io/laurentpayot/pen/RweNNQR) inserts the identicon into an `img` tag `src` attribute. It also uses React `useMemo` to memoize the identicon.\n\n```jsx\nimport { minidenticon } from 'minidenticons'\nimport { useMemo } from 'react'\n\nconst MinidenticonImg = ({ username, saturation, lightness, ...props }) =\u003e {\n  const svgURI = useMemo(\n    () =\u003e 'data:image/svg+xml;utf8,' + encodeURIComponent(minidenticon(username, saturation, lightness)),\n    [username, saturation, lightness]\n  )\n  return (\u003cimg src={svgURI} alt={username} {...props} /\u003e)\n}\n```\nYou can then use this component with `img` props such as `width` and `height` along with minidenticons ones. All props except `username` are optional.\n\n```html\n\u003cMinidenticonImg username=\"laurent\" saturation=\"90\" width=\"150\" height=\"150\" /\u003e\n```\nFor a TypeScript version of this example see the [original issue comment](https://github.com/laurentpayot/minidenticons/issues/2#issuecomment-1485545388) by [Dan Yishai](https://github.com/danyi1212).\n\n### Workbox\n\nIn this example using [Workbox](https://developer.chrome.com/docs/workbox/), images with a path ending with `minidenticons/\u003cusername\u003e.svg` are generated by the service worker and cached for one year.\n\n```javascript\nimport { minidenticon } from 'minidenticons'\nimport { registerRoute } from 'workbox-routing'\n\nregisterRoute(\n  /minidenticons\\/[^\\/]+\\.svg$/,\n  async ({ url }) =\u003e {\n    const username = url.pathname.match(/([^\\/]+)\\.svg$/)[1]\n    return new Response(\n      minidenticon(username),\n      { headers: { \"Content-Type\": \"image/svg+xml\", \"Cache-Control\": \"max-age=31536000\" } }\n    )\n  }\n)\n```\n\n## Rust\n\nA [Rust](https://www.rust-lang.org/) port of Minidenticons was made by Théo Battrel: [`minidenticons-rs`](https://gitlab.com/Emplis/minidenticons-rs).\n\n## Elm\n\nFor [Elm](https://elm-lang.org/) enthusiasts there is a Minidenticons package on the Elm package repository: [`minidenticons-elm`](https://package.elm-lang.org/packages/laurentpayot/minidenticons-elm/latest).\n\n## Collisions\n\nYou will always get the same identicon for a given username. But it is not impossible to have different usernames with the same identicon. That's a [collision](https://en.wikipedia.org/wiki/Hash_collision).\n\nGenerated identicons are 5×5 matrices with vertical symmetry, and can have 9 different hues for the same saturation and lightness.\nThis means there are 2\u003csup\u003e(3×5)\u003c/sup\u003e × 9 = 294,912 different identicons possible, but duplicate identicons are inevitable when using a lot of them. It shouldn’t matter as identicons should not be used solely to identify an user, and should always be coupled to a *unique* username :wink:\n\nThe `npm test` command results below show that you have less than a 2 percent chance to generate a duplicate identicon when already using 10,000 of them.\n\n```text\n0 collisions out of 100 (0.00%)\n0 collisions out of 200 (0.00%)\n0 collisions out of 300 (0.00%)\n0 collisions out of 400 (0.00%)\n0 collisions out of 500 (0.00%)\n0 collisions out of 600 (0.00%)\n0 collisions out of 700 (0.00%)\n0 collisions out of 800 (0.00%)\n1 collisions out of 900 (0.11%)\n1 collisions out of 1000 (0.10%)\n8 collisions out of 2000 (0.40%)\n14 collisions out of 3000 (0.47%)\n22 collisions out of 4000 (0.55%)\n37 collisions out of 5000 (0.74%)\n58 collisions out of 6000 (0.97%)\n75 collisions out of 7000 (1.07%)\n99 collisions out of 8000 (1.24%)\n129 collisions out of 9000 (1.43%)\n163 collisions out of 10000 (1.63%)\n```\n\n## License\n\n[MIT](https://github.com/laurentpayot/minidenticons/blob/main/LICENSE)\n\n## Stargazers :heart:\n\n[![Stargazers repo roster for @laurentpayot/minidenticons](http://reporoster.com/stars/laurentpayot/minidenticons)](https://github.com/laurentpayot/minidenticons/stargazers)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flaurentpayot%2Fminidenticons","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flaurentpayot%2Fminidenticons","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flaurentpayot%2Fminidenticons/lists"}