{"id":30068618,"url":"https://github.com/graphieros/target-highlight","last_synced_at":"2025-08-08T10:46:18.574Z","repository":{"id":288723544,"uuid":"969022606","full_name":"graphieros/target-highlight","owner":"graphieros","description":"A lightweight, zero‑dependency JavaScript library to spotlight DOM elements. Ideal to create tutorials!","archived":false,"fork":false,"pushed_at":"2025-05-22T04:00:57.000Z","size":144,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-25T23:26:59.665Z","etag":null,"topics":["dom","highlight","overlay","spotlight","tour"],"latest_commit_sha":null,"homepage":"","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/graphieros.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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-04-19T07:51:51.000Z","updated_at":"2025-06-02T09:51:45.000Z","dependencies_parsed_at":null,"dependency_job_id":"fd7efd45-d283-47e4-90fb-f3b6e287d3c4","html_url":"https://github.com/graphieros/target-highlight","commit_stats":null,"previous_names":["graphieros/target-highlight"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/graphieros/target-highlight","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphieros%2Ftarget-highlight","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphieros%2Ftarget-highlight/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphieros%2Ftarget-highlight/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphieros%2Ftarget-highlight/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/graphieros","download_url":"https://codeload.github.com/graphieros/target-highlight/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphieros%2Ftarget-highlight/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269410055,"owners_count":24412147,"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","status":"online","status_checked_at":"2025-08-08T02:00:09.200Z","response_time":72,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["dom","highlight","overlay","spotlight","tour"],"created_at":"2025-08-08T10:46:16.692Z","updated_at":"2025-08-08T10:46:18.533Z","avatar_url":"https://github.com/graphieros.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# target-highlight\n\n[![npm](https://img.shields.io/npm/v/target-highlight)](https://github.com/graphieros/target-highlight)\n[![GitHub issues](https://img.shields.io/github/issues/graphieros/target-highlight)](https://github.com/graphieros/target-highlight/issues)\n[![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/graphieros/target-highlight?tab=MIT-1-ov-file#readme)\n[![npm](https://img.shields.io/npm/dt/target-highlight)](https://github.com/graphieros/target-highlight)\n\nA lightweight, zero‑dependency JavaScript library to spotlight DOM elements with a customizable overlay, border, padding, and optional tooltip. Single or multiple elements can be highlighted, using usual selectors.\n\n[DEMO](https://target-highlight.graphieros.com)\n\n**target-highlight** can be used for example to setup a tutorial by highlighting elements.\n\n## Features\n\n- **Overlay** the page, carving out “holes” around target elements\n- **Customizable** overlay color, border color, width, radius, padding\n- **Tooltip** support (single or per‑element) with automatic positioning\n- **Configurable** via options or global defaults\n\n---\n\n## Installation\n\n```bash\nnpm install target-highlight\n# or\nyarn add target-highlight\n```\n\n## Usage\n\n```ts\nimport {\n  targetHighlight,\n  targetHide,\n  defaultConfig,\n  HighlightOptions,\n} from \"target-highlight\";\n\n// Define options\nconst options = {\n  overlayColor: \"#00000080\", // all color formats will work\n  borderColor: \"red\", // all color formats will work\n  singleTooltip: true,\n  padding: \"2px\", // same as css\n  borderRadius: 2,\n  overlayZIndex: 2,\n  hidePointerEvents: false,\n  scrollToTarget: {\n    // Use the same options as the native scrollIntoView api\n    behavior: \"smooth\",\n    block: \"center\",\n    inline: \"center\",\n  },\n  nextCallback: () =\u003e {}, // use your callback when clicking on a button with an id of target-highlight-button-previous\n  previousCallback: () =\u003e {}, // use your callback when clicking on a button with an id of target-highlight-button-previous\n  stopCallback: () =\u003e {}, // use your callback when clicking on a button with an id of target-highlight-button-stop\n  tooltip: \"My content\", // can also be a callback returning html content\n  forceTooltipPosition: null, // 'top' | 'right' | 'bottom' | 'left' | null, default: null\n  useResizeObserver: true, // If true, will trigger a re-render when the highlighted element resizes\n  blockedKeys: [], // Add keyboard keys that will be inactive when the application is running\n};\n\n// Target an element using any selector\n\ntargetHighlight(\"#myDiv\", {\n  ...options,\n  tooltip: \"This is my div\",\n});\n\n// Or target many elements\ntargetHighlight(\".myClass\", options);\n\n// Remove all highlights\ntargetHide();\n```\n\n## Customize the tooltip\n\nTarget the following css class to customize the tooltip:\n\n```css\n.target-highlight-tooltip {\n}\n```\n\nThe tooltip can also be passed a callback returning html content:\n\n```js\ntargetHighlight(\"#myDiv\", {\n  ...config,\n  tooltip: () =\u003e {\n    return `\n      \u003cdiv\u003e\n        My custom tooltip\n      \u003c/div\u003e\n    `;\n  },\n});\n```\n\nWhen highlighting multiple elements, you may need to show individual tooltips on each element.\nUse the data-target-highlight-tooltip attribute on the highlighted elements to setup the individual tooltip contents. You can also use the data-target-highlight-tooltip-position to force the tooltip position ('top' | 'right' | 'bottom' | 'left'). In this case, you won't need the tooltip option normally passed to targetHighlight. Bear in mind using data attributes, the tooltip content can only be a string.\n\n```html\n\u003cdiv\n  class=\"mySelection\"\n  data-target-highlight-tooltip=\"This is div 1\"\n  data-target-highlight-tooltip-position=\"bottom\"\n\u003e\n  Some content\n\u003c/div\u003e\n\u003cdiv\n  class=\"mySelection\"\n  data-target-highlight-tooltip=\"This is div 2\"\n  data-target-highlight-tooltip-position=\"left\"\n\u003e\n  Some other content\n\u003c/div\u003e\n```\n\n## Defining steps\n\nYou can create a scenario to move from step to step.\nAdd data-step=\"step\" on the elements part of the scenario, where step is a number.\n\n```js\n// Define step variables\nconst step = {\n  current: 0,\n  max: 5,\n};\n\n// Define callbacks in options\nconst options = {\n  nextCallback: () =\u003e moveStep(\"next\"),\n  previousCallback: () =\u003e moveStep(\"previous\"),\n  stopCallback: targetHide,\n};\n\n// Define blocked keys\nconst blockedKeys = [\" \", \"Tab\"];\n\n// Define a function to call the library and apply event listeners\n// In this example, chevron icons are added as plain svg\n// Buttons with id #target-highlight-button-previous and #target-highlight-button-next will be recognized by the library, and events attached to them.\nfunction applySteps() {\n  targetHighlight(`[data-step=\"${step.current}\"]`, {\n    ...options,\n    blockedKeys,\n    tooltip: () =\u003e {\n      return `\u003cdiv style=\"position:relative; padding: 0 24px\"\u003eThis is step ${step.value}\u003c/div\u003e\u003cbutton id=\"target-highlight-button-previous\" style=\"position: absolute; top: 50%; left: 0; transform: translateY(-50%)\"\u003e${chevronLeftIcon}\u003c/button\u003e\u003cbutton id=\"target-highlight-button-next\" style=\"position: absolute; top: 50%; right: 0; transform: translateY(-50%)\"\u003e${chevronRightIcon}\u003c/button\u003e`;\n    },\n  });\n\n  setTimeout(() =\u003e {\n    applyStepListeners(options);\n  }, 10);\n}\n\n// Define a function to move through the steps\nfunction moveStep(direction) {\n  if (direction === \"next\") {\n    step.current += 1;\n    if (step.current \u003e step.max) {\n      step.current = 0;\n    }\n  } else {\n    step.current -= 1;\n    if (step.current \u003c 0) {\n      step.current = step.max;\n    }\n  }\n  applySteps();\n}\n```\n\n## Ignore elements\n\nUse the data-target-highlight ignore data attribute on elements never to be highlighted:\n\n```html\n\u003c!-- When targeting the .selection class, only one element will be highlighted --\u003e\n\u003cdiv class=\"selection\"\u003eI will be selected\u003c/div\u003e\n\u003cdiv class=\"selection\" data-target-highlight-ignore\u003eI will not be selected\u003c/div\u003e\n```\n\n## Blocked keys\n\nCombine `hidePointerEvents: false` with blocked keys, to prevent events outside of the tour.\nList of all the available blockable keys:\n\n```ts\ntype KeyboardNavigationKey =\n  | \" \"\n  | \"Tab\"\n  | \"Enter\"\n  | \"ArrowUp\"\n  | \"ArrowDown\"\n  | \"ArrowLeft\"\n  | \"ArrowRight\"\n  | \"Home\"\n  | \"End\"\n  | \"PageUp\"\n  | \"PageDown\"\n  | \"Escape\";\n```\n\nSet blocked keys in the options object:\n\n```js\nblockedKeys: [\n  \" \",\n  \"Tab\",\n  \"Enter\",\n  \"ArrowUp\",\n  \"ArrowDown\",\n  \"ArrowLeft\",\n  \"ArrowRight\",\n  \"Home\",\n  \"End\",\n  \"PageUp\",\n  \"PageDown\",\n  \"Escape\",\n];\n```\n\nBlocked events will be restored when `targetHide` is called.\n\n## Tooltip transitions\n\nThis library does not inject CSS. To enable tooltip transitions, add for example the following to your app’s global styles:\n\n```css\n.target-highlight-tooltip {\n  opacity: 1;\n  transition: opacity 0.3s;\n  will-change: opacity;\n}\n\n.target-highlight-tooltip.fade-in {\n  opacity: 0;\n  animation: fadeIn 0.3s forwards;\n}\n\n.target-highlight-tooltip.fade-out {\n  opacity: 1;\n  animation: fadeOut 0.3s forwards;\n  pointer-events: none;\n}\n\n@keyframes fadeIn {\n  to {\n    opacity: 1;\n  }\n}\n\n@keyframes fadeOut {\n  to {\n    opacity: 0;\n  }\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgraphieros%2Ftarget-highlight","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgraphieros%2Ftarget-highlight","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgraphieros%2Ftarget-highlight/lists"}