{"id":24401719,"url":"https://github.com/thomasdev-de/jquery-heatmap","last_synced_at":"2026-02-10T20:32:43.577Z","repository":{"id":272144177,"uuid":"914798380","full_name":"ThomasDev-de/jquery-heatmap","owner":"ThomasDev-de","description":"A jQuery plugin for creating interactive heatmap visualizations.","archived":false,"fork":false,"pushed_at":"2025-01-24T20:52:12.000Z","size":81,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-23T09:35:15.704Z","etag":null,"topics":["heatmap","interactive","jquery","plugin","visualization"],"latest_commit_sha":null,"homepage":"https://webcito.de/jquery-heatmap","language":null,"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/ThomasDev-de.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,"zenodo":null}},"created_at":"2025-01-10T10:26:15.000Z","updated_at":"2025-08-04T20:53:14.000Z","dependencies_parsed_at":"2025-04-23T01:02:12.186Z","dependency_job_id":"1b40f760-2ad9-4432-b125-513e64ec96d8","html_url":"https://github.com/ThomasDev-de/jquery-heatmap","commit_stats":null,"previous_names":["thomasdev-de/jquery-heatmap"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/ThomasDev-de/jquery-heatmap","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThomasDev-de%2Fjquery-heatmap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThomasDev-de%2Fjquery-heatmap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThomasDev-de%2Fjquery-heatmap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThomasDev-de%2Fjquery-heatmap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ThomasDev-de","download_url":"https://codeload.github.com/ThomasDev-de/jquery-heatmap/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThomasDev-de%2Fjquery-heatmap/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29314705,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-10T17:48:59.043Z","status":"ssl_error","status_checked_at":"2026-02-10T17:45:37.240Z","response_time":65,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["heatmap","interactive","jquery","plugin","visualization"],"created_at":"2025-01-20T00:46:14.657Z","updated_at":"2026-02-10T20:32:43.559Z","avatar_url":"https://github.com/ThomasDev-de.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# jQuery Heatmap Plugin\n\nThis jQuery plugin generates a visually appealing and interactive heatmap visualization.\nIt maps data intensity to color variations, providing an intuitive overview of your dataset.\n\n![Heatmap](demo/heatmap.png)\n\n---\n\n## Features\n\n- **Data-Driven Visualization:** Displays data in a heatmap where the color intensity corresponds to data values.\n- **Dynamic Data Handling:** Supports both static data arrays and dynamic data fetching via AJAX requests.\n- **Custom Query Parameters:** Define additional query parameters dynamically using the `queryParams` function without\n  overriding standard values like `startDate` and `endDate`.\n- **Customizable Design:** Adjust cell sizes, the gap (gutter) between cells, and color gradients.\n- **Localization Support:** Automatically adjusts week start days and date formatting based on locale settings.\n- **Interactive Tooltips:** Displays tooltips with date and associated data values when hovering over cells.\n- **Comprehensive Error Handling:** Handles errors from data fetching or invalid input gracefully.\n- **Easy Integration:** Designed with an intuitive jQuery syntax for effortless integration into web projects.\n\n---\n\n## What's New in Version 1.0.3\n\n1. **Default Date Values:**\n    - Removed outdated options `startDate` and `endDate`. Date handling is now fully dynamic based on the provided data.\n\n2. **Query Parameters (`queryParams`):**\n    - A new function allows users to add query parameters dynamically as part of the query string.\n\n3. **Week Calculation:**\n    - Weeks are now calculated dynamically without the need for `startDate` or `endDate` configuration.\n\n4. **Enhanced Color Mapping:**\n    - Define color gradients for different data intensity levels with flexible customization.\n\n5. **Debugging Option:**\n    - A new `debug` option allows you to log settings and queries to the browser console.\n\n6. **Automatic First Day of the Week:**\n    - The plugin determines the first day of the week automatically based on the provided locale.\n\n---\n## Requirements\n\n- **jQuery:** Requires jQuery 3.6 or higher.\n- **Moment:** Requires moment-with-locales.min.js ^2. Moment.js is required to reliably determine the first day of the week (e.g., Monday or Sunday).\n- **Browser Compatibility:** Works on modern browsers with JavaScript enabled.\n- **Dependencies:** No additional external libraries required.\n---\n## Installation\n\n1. **Include jQuery and the Heatmap Plugin:**\n   ```html\n   \u003cscript src=\"/vendor/components/jquery/jquery.min.js\"\u003e\u003c/script\u003e\n   \u003cscript src=\"/vendor/moment/moment/min/moment-with-locales.min.js\"\u003e\u003c/script\u003e\n   \u003cscript src=\"dist/jquery.heatmap.min.js\"\u003e\u003c/script\u003e\n   ```\n\n2. **Create a Container Element:**\n   ```html\n   \u003cdiv id=\"heatmap-container\"\u003e\u003c/div\u003e\n   ```\n\n3. **Initialize the Plugin:**\n   ```javascript\n   $('#heatmap-container').heatmap({\n       data: [/* Your data array or API URL */],\n       // Dates automatically inferred from data, or configurable if necessary,\n       // Example: startDate: '2023-01-01', endDate: '2023-12-31',\n       locale: 'en-US',\n       // ...other options\n   });\n   ```\n\n---\n\n## Options\n\n| Option               | Description                                                                                                  | Default Value                                                              |\n|----------------------|--------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|\n| **`data`**           | Array of data points or a URL from which data will be fetched.                                               | `null`                                                                     |\n| **`queryParams`**    | Function for adding query parameters dynamically (e.g., `{ locale: 'en-US' }`).                              | `() =\u003e {}`                                                                 |\n| **`cellSize`**       | The size of each heatmap cell in pixels.                                                                     | `14px`                                                                     |\n| **`colors`**         | An object defining the heatmap's color gradient. Keys are thresholds between `0` and `1`. Values are colors. | See gradient below                                                         |\n| **`locale`**         | Locale for displaying dates and determining the first day of the week.                                       | `en-US`                                                                    |\n| **`debug`**          | If `true`, settings and queries are logged to the console.                                                   | `false`                                                                    |\n| **`titleFormatter`** | A function to format the tooltip content, receiving locale, date, and count as arguments.                    | `(locale, date, count) =\u003e date.toLocaleDateString(locale) + \" - \" + count` |\n\n---\n\n## Methods\n\n### Initialize:\n\n```javascript\n$('#heatmap-container').heatmap(options);\n```\n\n### Update Settings:\n\n```javascript\n$('#heatmap-container').heatmap('updateOptions', {\n    data: [...urlOrDataSet],\n    cellSize: 30,\n    ...\n});\n```\n\n---\n\n### Events\n\nThis plugin supports specific events, allowing developers to respond to various states and actions.\n\n- **`init.heatmap`**  \n  Triggered after the heatmap has been successfully initialized.  \n  Example:\n  ```javascript\n  $('#heatmap').on('init.heatmap', function (event, element) {\n      console.log('Heatmap has been initialized!', element);\n  });\n  ```\n\n- **`post.heatmap`**  \n  Triggered after the heatmap has been fully rendered, including all data and visual elements. The event includes the element and the rendered data.  \n  Example:\n  ```javascript\n  $('#heatmap').on('post.heatmap', function (event, element, data) {\n      console.log('Heatmap rendering completed!', element);\n      console.log('Rendered data:', data);\n  });\n  ```\n\n---\n\n## Example\n\n### Simple Data Initialization:\n\n```javascript\n$('#heatmap-container').heatmap({\n    data: [\n        {date: '2024-01-01', count: 5},\n        {date: '2024-01-02', count: 10},\n        // Dynamic date handling relies on this data array\n    ],\n\n    startDate: '2024-01-01',\n    endDate: '2024-12-31',\n    colors: {\n        0: '#ebedf0',\n        0.25: '#c6e48b',\n        0.5: '#7bc96f',\n        0.75: '#239a3b',\n        1: '#196127'\n    },\n});\n```\n\n### Query Parameters Example:\n\nInclude additional query parameters dynamically using the `queryParams` function:\n\n```javascript\n$('#heatmap-container').heatmap({\n    data: '/api/data',\n    queryParams: () =\u003e {\n        return {\n            locale: 'en-US',\n            userId: 123, // Add custom parameters\n        };\n    },\n});\n```\n\n---\n\n## Debugging\n\nEnable debugging to log data and settings in the browser console.\nThis can be useful for development and error diagnosis:\n\n```javascript\n$('#heatmap-container').heatmap({\n    startDate: '2024-01-01',\n    endDate: '2024-12-31',\n});\n```\n\n---\n\n### Heatmap Color Customization\n\nThe `colors` option in the heatmap plugin defines the color intensity mapping for the heatmap cells.\nThe colors represent different intensity levels based on the data provided.\nEach key in the `colors` object is a threshold between `0` and `1`,\nand the corresponding value is the color that will be applied.\n\n---\n\n#### Default Color Mapping\n\nBy default, the plugin provides the following color mapping:\n\n```\ncolors: {\n    0: '#ebedf0',   // No intensity (lowest)\n    0.25: '#c6e48b', // Low intensity\n    0.5: '#7bc96f',  // Medium intensity\n    0.75: '#239a3b', // High intensity\n    1: '#196127'     // Maximum intensity\n}\n```\n\n- **0:** This corresponds to no activity or zero intensities and typically uses a light, almost \"empty\" color.\n- **1:** This is the highest activity or maximum intensity and uses the most vibrant or darkest defined color.\n- Intermediate thresholds (e.g., `0.25`, `0.5`, and `0.75`) use colors to provide a gradient effect.\n\n---\n\n#### How Colors Work\n\nEach value (`count`) in your data is converted to a relative intensity based on the range of the data\n(minimum to maximum counts).\nThe plugin calculates the position of the data point and determines the corresponding color from the `colors` map.\n\nThe calculation respects the following principles:\n- **Logarithmic scaling:** Data is scaled logarithmically to ensure even distribution of color across high-variable datasets.\n- **Clamping:** Values below the minimum or above the maximum are clamped to use the lowest or highest defined colors, respectively.\n\n---\n\n#### Example: Custom Color Mapping\n\nYou can provide your own custom mapping of thresholds to colors based on the specific requirements of your heatmap visualization.\nHere's an example:\n\n```javascript\n$('#heatmap-container').heatmap({\n    colors: {\n        0: '#f0f0f0',  // No intensity\n        0.3: '#add8e6', // Light blue for low intensity\n        0.6: '#0000ff', // Blue for medium intensity\n        1: '#00008b'    // Dark blue for high intensity\n    }\n});\n```\n\nIn this example:\n- Data points that correspond to approximately 30% of the maximum intensity will appear light blue.\n- Data points at 60% of the maximum intensity will appear as medium blue.\n- The highest intensity will appear as dark blue.\n\n---\n\n#### Gradient Tipps\n\n- Use light colors for low thresholds (e.g., `0`) and darker or more vibrant colors for high thresholds (e.g., `1`) to provide a clear visual hierarchy.\n- The `colors` object supports any CSS-compatible color format, such as HEX (`#ffffff`), RGB (`rgb(255, 255, 255)`), or named colors (`red`).\n- For large datasets with higher variability, consider using more intermediate threshold levels to create a smoother gradient.\n\n---\n\n#### Example: Smooth Gradient\n\nFor a smoother gradient with multiple intermediate values:\n\n```javascript\n$('#heatmap-container').heatmap({\n    colors: {\n        0: '#ffffff',  // White (lowest intensity)\n        0.1: '#f7d7d0',\n        0.2: '#f0a29a',\n        0.5: '#e55241',\n        0.75: '#be2d1b',\n        1: '#7a1410'   // Dark red (highest intensity)\n    }\n});\n```\n\nThe more intermediate values you define, the smoother the gradient will appear.\n\nBy customizing the `colors` option,\nyou can tailor the heatmap's appearance to fit your project's visual requirements more effectively.\n\n---\n\n## Contributing\n\nContributions are welcome! Feel free to report bugs, request features, or submit pull requests.\n\n---\n\n## License\n\nThis plugin is available under the [MIT Licence](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthomasdev-de%2Fjquery-heatmap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthomasdev-de%2Fjquery-heatmap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthomasdev-de%2Fjquery-heatmap/lists"}