{"id":16513785,"url":"https://github.com/wintercounter/protip","last_synced_at":"2025-04-04T18:10:41.004Z","repository":{"id":45008407,"uuid":"38879972","full_name":"wintercounter/Protip","owner":"wintercounter","description":"A new generation jQuery Tooltip plugin","archived":false,"fork":false,"pushed_at":"2019-03-22T23:51:44.000Z","size":1501,"stargazers_count":359,"open_issues_count":10,"forks_count":38,"subscribers_count":22,"default_branch":"master","last_synced_at":"2025-03-28T23:42:03.560Z","etag":null,"topics":["jquery","jquery-plugin","protip","tooltip"],"latest_commit_sha":null,"homepage":"http://protip.rocks","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/wintercounter.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":"2015-07-10T12:47:22.000Z","updated_at":"2024-01-16T20:04:46.000Z","dependencies_parsed_at":"2022-08-25T13:41:44.615Z","dependency_job_id":null,"html_url":"https://github.com/wintercounter/Protip","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wintercounter%2FProtip","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wintercounter%2FProtip/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wintercounter%2FProtip/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wintercounter%2FProtip/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wintercounter","download_url":"https://codeload.github.com/wintercounter/Protip/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247226215,"owners_count":20904465,"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":["jquery","jquery-plugin","protip","tooltip"],"created_at":"2024-10-11T16:10:17.588Z","updated_at":"2025-04-04T18:10:40.984Z","avatar_url":"https://github.com/wintercounter.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Dependency Status](https://david-dm.org/wintercounter/Protip.svg)\n[![Join the chat at https://gitter.im/wintercounter/Protip](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/wintercounter/Protip?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n\n---\n# Features in Brief\n\n- 49 position\n- Live refresh of tooltip options.\n- Live element checking (element removed? -\u003e tooltip should disappear).\n- Gravity: find a better position if it won't fit to the screen.\n- DOM targets: append into the root or into another target element.\n- Placements: outside, inside, border, center\n- Click activated and sticky tooltips.\n- Custom HTML content\n- Interactive tooltips\n- In/Out delays\n- Auto-hide\n- Icon support\n- Skins, sizes, schemes\n- Animations support\n- Mixins (CSS only, JS based coming soon)\n- Custom event callbacks\n- UMD Support\n\n\n---\n# Introduction\nAt the company I working for we use many tooltips for several purposes. Especially our admin area/control panel side has heavy tooltip usage. There were several unusual requests which always required to develop new features into our existing plugin. Now I've created Protip, a new generation of tooltips. It's not so lightweight but it doesn't intends to be. We needed a solution which can fit into every scenario we face with.\n\n---\n# Installation\n\n## The simple way \n\nInclude the **protip.min.css** file in your `\u003chead\u003e` tag:\n\n```html\n\u003clink rel=\"stylesheet\" href=\"//min.gitcdn.xyz/repo/wintercounter/Protip/master/protip.min.css\"\u003e\n```\n\nInclude the **protip.min.js** file before your closing `\u003c/body\u003e` tag (but after jQuery is included):\n\n```html\n\u003cscript src=\"//min.gitcdn.xyz/repo/wintercounter/Protip/master/protip.min.js\"\u003e\u003c/script\u003e\n```\n\n## Get files using npm\n```\nnpm install protip --save\n```\n\n## Get files using bower\n```\nbower install protip\n```\n\n## Initialize plugin\nTo initialize the plugin just insert `$.protip();` in your `$(document).ready();` section in case you already have.\nIf you don't then create one:\n\n```javascript\n$(document).ready(function(){\n    $.protip();\n});\n```\n\n**You may pass a configuration object here also:** `$.protip([configObject]);`\n\n---\n# Usage\n## Configuration\nYou may need some global configurations on the behaviors of your tooltips. You can pass some configuration options at initialization as an object.\n\n```javascript\n// Available options with default values\n$.protip({\n    /** @type String    Selector for protips */\n    selector:           C.DEFAULT_SELECTOR,\n    /** @type String    Namespace of the data attributes */\n    namespace:          C.DEFAULT_NAMESPACE,\n    /** @type String    Template of protip element */\n    protipTemplate:     C.TEMPLATE_PROTIP,\n    /** @type String    Template of the arrow element */\n    arrowTemplate:      C.TEMPLATE_ARROW,\n    /** @type String    Template of protip icon */\n    iconTemplate:       C.TEMPLATE_ICON,\n    /** @type Boolean   Should we observe whole document for assertions and removals */\n    observer:           true,\n    /** @type Number    Default time for onResize event timeout. */\n    delayResize:        100,\n    /** @type Object    Default data-pt-* values for a tooltip */\n    defaults:           {...}\n});\n```\n\n| Property       | Default  | Details   |\n|----------------|----------|-----------|\n| **selector**       | .protip  | We will use this selector to identify elements with protip.  |\n| **namespace**      | pt       | data-[NAMESPACE]-* |\n| **protipTemplate** | See code | Template of a protip. Variables ({}) will get replaced. |\n| **arrowTemplate**  | See code | Template of a protip arrow. |\n| **iconTemplate**   | See code | Template of a protip with icon. |\n| **observer**       | true     | If true, we will watch for changes in the DOM and check if a protip needs to be showed or removed. |\n| **delayResize**    | 100      | Default time for onResize event timeout. After a resize, we need to reposition the tooltips, but don't want to run on every fired resize event. |\n| **defaults**       | {...}    | Default (global) values for a tooltip. Override any available `data-pt-*` attributes. |\n\n## Attach tooltips to elements\nTooltips are controlled over data attributes. Seriously, you can control every aspect of your tooltip from the markup, no additional JavaScript code is required.\n\n```html\n\u003ca href=\"#bar\" class=\"protip\" data-pt-title=\"You must be at least 18!\"\u003e\n    Go to the bar!\n\u003c/a\u003e\n```\n\nWhat I did here was that added a protip class to my element, then defined a tooltip text in the in the data-pt-title attribute.\nProtip related attributes will always get a pt namespace so Protip won't conflict with your existing data attributes.\n\n## Available attributes [data-pt-*]\n| Attribute   | Default  | Type         | Details                                                                                                                                                                                                                                 |\n|-------------|----------|--------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| **trigger**     | 'hover'   | *String*       | How you want to trigger this tooltip? Available values: **hover**, **click**, **click2**, **sticky** (sticky will be shown on load; click2 won't listen to body clicks)                                                                                                                                   |\n| **title**       | null      | *String*       | The tooltip content text. Alternatively you may provide a selector (ID or class) starting with **#** or **.** to get data (*even whole HTML*) from another DOM element's content. Example: `\u003cdiv id=\"tooltipContent\"\u003e\u003cem\u003eThis is my tooltips content\u003c/em\u003e\u003c/div\u003e`. Also you may use `:next`, `:prev` or `:this` which allows you to get the content of the next, prev or this element immediatelly.                                       |\n| **delay-in**    | 0         | *Number*       | Delay of showing a tooltip. Handy in cases when you want to prevent tooltips on quick mouseovers.                                                                                                                                       |\n| **delay-out**   | 0         | *Number*       | Delay of hiding the tooltip. Handy in cases you have clickable content in the tooltip for example.                                                                                                                                      |\n| **interactive** | false     | *Bool*         | If **true**, protip will use a default **250ms** as *delayOut* for clickable contents.                                                                                                                                                            |\n| **gravity**     | true      | *Bool, String* | Gravity will check your tooltip before showing it and it will search for better positions if the tooltip won't fit to viewport. Gravity has **multiple options available**, there is a separate section in the documentation about gravity. |\n| **offset-top**  | 0         | *Int*          | Adjust the **Y** position of the tooltip.                                                                                                                                                                                                   |\n| **offset-left** | 0         | *Int*          | Adjust the **X** position of the tooltip.                                                                                                                                                                                                   |\n| **position**    | 'bottom'  | *String*       | Preferred position. **Check Positions section** for available options and details.                                                                                                                                                           |\n| **placement**   | 'outside' | *String*       | Placement of the tooltip inside the element. Available values are: outside, inside, border and center.                                                                                                                                                       |\n| **classes**     | null      | *String*       | These classes will be added to the tooltip which may enable additional styling for example.                                                                                                                                             |\n| **arrow**       | true      | *Bool*         | Hide arrow from this tooltip. At initialization there is an option to set the size of the arrow. Protip will calculate this into positions.                                                                                              |\n| **width**       | 300       | *Int, String*  | This is the default **max-width** for the tooltip. If you need fixed width, write as this: **300!**                                                                                                                                             |\n| **icon**        | false     | *Bool, String* | Adds icon template to the tooltip markup with the specified icon **class**.                                                                                                                                                                 |\n| **observer**    | false     | *Bool*         | If **true**, we will attach an observer to the source element and watch for changes. *For example if you change the data-pt-title attribute, the tooltip title will be changed also.*                                                         |\n| **target**      | 'body'    | *Bool, String* | We will append the tooltip to this **selector**. Use **true** if you want to append into the source element.                                                                                                                                    |\n| **skin**        | 'default' | *Bool, String* | Skin to apply only to this tooltip. (Currently available: default, square)                                                                                                                                   |\n| **size**        | 'normal'  | *String*       | tiny, small, normal, big, large                                                                                                                                 |\n| **scheme**      | 'pro'     | *String*       | Color scheme to use. [See the scheme list](#list-of-available-schemes)                                                                                                                           |\n| **animate**     | undefined | *Bool, String* | Animation type based on Animate.css. [See Animations](#animations)                                                                                                                                    |\n| **auto-hide**   | false     | *Bool, Number* | Tooltip will hide itself automatically after this timeout (milliseconds).                                                                                                                                    |\n| **auto-show**   | false     | *Bool*         | Automatically show tooltip for this element on load (stickies will be shown anyway).                                                                                                                                    |\n| **mixin**       | undefined | *String*       | Tooltip mixins to use. Separated by spaces.                                                                                                                                    |\n\n## jQuery Helpers\n```javascript\nvar el = $('.el');\n\n// Set tooltip to the element.\nel.protipSet([options]);\n\n// Show the tooltip of this element. Same as set, but it will also show.\nel.protipShow([options]);\n\n// Hide the tooltip of this element.\nel.protipHide();\n\n// Toggle the tooltip of this element.\nel.protipToggle();\n\n// Hide all tooltips inside of this element.\nel.protipHideInside();\n\n// Show all tooltips inside of this element.\nel.protipShowInside();\n\n// Toggle all tooltips inside of this element.\nel.protipToggleInside();\n\n// Custom show event\nel.on('protipshow', function(ItemInstance){});\n\n// Custom hide event\nel.on('protiphide', function(ItemInstance){});\n\n// Custom ready event\n// Note that ready will fires after 10ms after it's actually ready.\n// This helps your scripts to catch up.\nel.on('protipready', function(ItemInstance){});\n\n// Use console.log(ItemInstance) in the callback to check what options you have.\n```\n\n### Example\n```html\n\u003cdiv class=\"my-el protip\" data-pt-title=\"My element\"\u003e\u003c/div\u003e\n```\n\n```javascript\nvar el = $('.my-el');\n\n// Shows tooltip with title: \"My element\"\nel.protipShow();\n\n// Shows tooltip with title: \"My new title\"\nel.protipShow({\n    title: 'My new title'\n});\n\n// Changed trigger from hover to click\nel.protipSet({\n    trigger: 'click'\n});\n\n// Changed trigger from hover to click and also show it\nel.protipShow({\n    trigger: 'click'\n});\n```\n\n---\n# Gravity\n\n## List of available positions\n- corner-left-top\n- top-left\n- top\n- top-right\n- corner-right-top\n- right-top\n- right\n- right-bottom\n- bottom-left\n- bottom\n- bottom-right\n- corner-right-bottom\n- left-top\n- left\n- left-bottom\n- corner-left-bottom\n\n![Available Protip positions](https://raw.githubusercontent.com/wintercounter/Protip/master/img/docs-positions.png)\n\n## data-pt-gravity\n\n### True/False\nIt will enable/disable the gravity option. In case it's true, protip is going to try all positions.\n\n### The 3 level of positions\n**Level 1** top, right, bottom, left\n**Level 2** All other except corners\n**Level 3** Even corners\n\nYou may define a level number. Set to **1** in case you want to you gravity only in the most common positions. **2** will trigger both **1** and **2**. ***3*** will trigger all of them.\n\n### Fully manual control\nSometimes you may need to have certain tooltips to have only 3 or 5 number of positions with custom offsets in all positions. There is a custom markup for this purpose:\n\n**Use only 2 position.**\n`data-pt-gravity=\"top-right; bottom-left\"`\n\n**Use only 2 position. With custom offset. (X, Y)**\n`data-pt-gravity=\"top-right 10; bottom-left -10 30\"`\n\n**Prioritize these position, then the others may come...**\n`data-pt-gravity=\"top-right; bottom-left; ...\"`\n\n*Mix as you want :)*\n\n## data-pt-placement\n\nThe placement attribute allows you to change the positioning behavior of the tooltip.\n\n- **outside**: This is the default behavior. It will place the tooltip outside the specified element.\n- **inside**: It will place the tooltip inside the specified element.\n- **border**: It will place the tooltip right onto the border of the specified element.\n- **center**: It's a special placement. It will place the tooltip to the exact center. No other positions applied.\n\n**Please note that you will probably want to disable arrows for other placements than `outside`.**\n\n---\n# Animations\nProtip has built-in support for **Animate.css** (https://daneden.github.io/animate.css/).\nYou simply need to use the same name found on the linked website.\n\nUsage:\n```html\n\u003cdiv class=\"protip\" data-pt-animate=\"bounceIn\"\u003e\u003c/div\u003e\n```\n\n**Protip's CSS doesn't include Animate.css. Download from here: //min.gitcdn.xyz/repo/daneden/animate.css/master/animate.css**\n\n---\n# Skins\nSkins are a little bit difficult at the moment and I'm looking forward to implement a much cleaner way.\nAnyway the markup won't change too drastic so the currently made skins should work in the future as well.\nPlease check Protip's SCSS files for more details. There are configurable maps,\nso you can easily add your own styles (schemes and sizes also).\n\n## List of available schemes\n- ![#da2e2b](https://placehold.it/15/da2e2b/000000?text=+) **pro**\n- ![#336699](https://placehold.it/15/336699/000000?text=+) **blue**\n- ![#802731](https://placehold.it/15/802731/000000?text=+) **red**\n- ![#339996](https://placehold.it/15/339996/000000?text=+) **aqua**\n- ![#333](https://placehold.it/15/333/000000?text=+) **dark**\n- ![#141414cc](https://placehold.it/15/141414cc/000000?text=+) **dark-transparent**\n- ![#000](https://placehold.it/15/000/000000?text=+) **black**\n- ![#339959](https://placehold.it/15/339959/000000?text=+) **leaf**\n- ![#613399](https://placehold.it/15/613399/000000?text=+) **purple**\n- ![#D457AA](https://placehold.it/15/D457AA/000000?text=+) **pink**\n- ![#E64426](https://placehold.it/15/E64426/000000?text=+) **orange**\n- ![#FFF](https://placehold.it/15/FFFFFF/000000?text=+) **white**\n\n---\n# Good to know stuff\n\n## .protip-target class\n\nIn case there is no `data-pt-title` specified, Protip will try to search a `.protip-target` class in the parents.\nIf it founds, the tooltip will be appended there else it will append right into the `body` (if nothing else is specified).\nThis is useful for example when using tooltips in overlays. Add `protip-target` class to your overlay container element\nwhich will solve `z-index` issues and tooltip removals when closing the overlay.\n\n## .protip-open class\n\nWhile a tooltip is opened, Protip will add `protip-open` class to your element to enable you to add custom styles for example.\n\n## .protip-close class\n\nIn case you need an element to close your tooltip (inside your tooltip, like an `X` or something), just add an element\nwith the class of `protip-close` which will trigger close on clicking it.\n\n## Auto-interactive link detection\n\nProtip will try to detect if your tooltip contains a link (by searching for `a` tags in it). If it does founds one, your\ntooltip will automatically become interactive so your users will be able to click the link inside the tooltip instead of closing it.\n\n## Why offset(top/left) is not working?\n\nThe `data-pt-offset-(left/top)` attributes are only have effect on the default position tooltip. If it gets re-positioned\nby Gravity it won't be added to the calculations. In case you need to position re-positioned tooltips, specify it in the\n`data-pt-gravity` tag using it's own syntax.\n\n```\ndata-pt-gravity=\"top 0 -15; bottom 0 15\"\n```\n\n## Command Buffer\n\nYou are allowed to call jQuery helpers (like protipShow/protipHide) before initialization of protip. This solves the problem with JavaScript file orders\nand calls before Protip is initialized, your commands will run after everything is done.\n\n## MutationObserver (IE8-10 Support)\n\nInternet Explorer supports Mutation Observers only from version 11. In case you need IE8-10 support you need to include a\nMutation Observer Polyfill. Simply include this script before Protip is loaded https://github.com/megawac/MutationObserver.js\n\n# Contribution, bugs, feature requests and suggestions\n\nContributions are always welcome. Just fork the repository, commit your changes and create a **Pull Request**.\n\nFor bugs, requests, suggestions, etc. please use the GitHub issue tracker at the Protip repository.\n\n---\n# Credits\n- nano template \"engine\" https://github.com/trix/nano\n- MutationObserver polyfill https://github.com/megawac/MutationObserver.js\n\n# Bookmarks\n- I want to use these in commit messages sometimes :) http://www.emoji-cheat-sheet.com/\n\n![](http://c.statcounter.com/10536219/0/6b821473/1/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwintercounter%2Fprotip","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwintercounter%2Fprotip","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwintercounter%2Fprotip/lists"}