{"id":13412312,"url":"https://github.com/rcarriga/nvim-notify","last_synced_at":"2025-05-13T23:03:57.174Z","repository":{"id":37440811,"uuid":"391206922","full_name":"rcarriga/nvim-notify","owner":"rcarriga","description":"A fancy, configurable, notification manager for NeoVim","archived":false,"fork":false,"pushed_at":"2025-04-13T12:53:46.000Z","size":248,"stargazers_count":3297,"open_issues_count":66,"forks_count":88,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-30T04:14:14.324Z","etag":null,"topics":["neovim","nvim"],"latest_commit_sha":null,"homepage":"","language":"Lua","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/rcarriga.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":"rcarriga"}},"created_at":"2021-07-30T23:19:09.000Z","updated_at":"2025-04-29T09:15:29.000Z","dependencies_parsed_at":"2024-02-17T10:25:24.388Z","dependency_job_id":"842c7692-1783-44f0-b824-59fd58617a97","html_url":"https://github.com/rcarriga/nvim-notify","commit_stats":{"total_commits":140,"total_committers":27,"mean_commits":5.185185185185185,"dds":0.2142857142857143,"last_synced_commit":"d333b6f167900f6d9d42a59005d82919830626bf"},"previous_names":[],"tags_count":75,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rcarriga%2Fnvim-notify","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rcarriga%2Fnvim-notify/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rcarriga%2Fnvim-notify/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rcarriga%2Fnvim-notify/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rcarriga","download_url":"https://codeload.github.com/rcarriga/nvim-notify/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254040348,"owners_count":22004511,"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":["neovim","nvim"],"created_at":"2024-07-30T20:01:23.328Z","updated_at":"2025-05-13T23:03:57.071Z","avatar_url":"https://github.com/rcarriga.png","language":"Lua","funding_links":["https://github.com/sponsors/rcarriga"],"categories":["Utility","Lua",":desktop_computer: Display modes","UI"],"sub_categories":["Cursorline",":bell: Notification","OS-specific"],"readme":"# nvim-notify\n\nA fancy, configurable, notification manager for NeoVim\n\n![notify](https://user-images.githubusercontent.com/24252670/130856848-e8289850-028f-4f49-82f1-5ea1b8912f5e.gif)\n\nCredit to [sunjon](https://github.com/sunjon) for [the design](https://neovim.discourse.group/t/wip-animated-notifications-plugin/448) that inspired the appearance of this plugin.\n\n* [Installation](#Installation)\n* [Usage](#usage)\n  - [Viewing History](#viewing-history)\n* [Configuration](#configuration)\n  - [Setup](#setup)\n  - [Highlights](#highlights)\n  - [Render Style](#render-style)\n  - [Animation Style](#animation-style)\n    + [Opening the window](#opening-the-window)\n    + [Changing the window](#changing-the-window)\n\n## Installation\n\n### Prerequisites\n\nMake sure to use a font which supported glyphs (icons), font can be found [here](https://github.com/ryanoasis/nerd-fonts).\n\n24-bit colour is required, which can be enabled by adding this to your init.lua\n```lua\nvim.opt.termguicolors = true\n```\n\nThen you can install nvim-notify with the package manager of your choice.\n\n[**dein**](https://github.com/Shougo/dein.vim):\n\n```vim\ncall dein#add(\"rcarriga/nvim-notify\")\n```\n\n[**vim-plug**](https://github.com/junegunn/vim-plug):\n\n```vim\nPlug 'rcarriga/nvim-notify'\n```\n\n[**packer**](https://github.com/wbthomason/packer.nvim):\n\n```lua\nuse 'rcarriga/nvim-notify'\n```\n\n## Usage\n\nSimply call the module with a message!\n\n```lua\nrequire(\"notify\")(\"My super important message\")\n```\n\nOther plugins can use the notification windows by setting it as your default notify function\n\n```lua\nvim.notify = require(\"notify\")\n```\n\nYou can supply a level to change the border highlighting\n\n```lua\nvim.notify(\"This is an error message\", \"error\")\n```\n\nUpdating an existing notification is also possible!\n\n![](https://user-images.githubusercontent.com/24252670/152641078-92f3da72-f49f-4705-aec8-86512693445f.gif)\n\n\nUse treesitter highlighting inside notifications with opacity changing\n\n![](https://user-images.githubusercontent.com/24252670/165042795-565878a3-9c6d-4c0b-ab0d-6858515835c5.gif)\n\nThere are a number of custom options that can be supplied in a table as the third argument.\nSee `:h NotifyOptions` for details.\n\nSample code for the first GIF above:\n\n```lua\nlocal plugin = \"My Awesome Plugin\"\n\nvim.notify(\"This is an error message.\\nSomething went wrong!\", \"error\", {\n  title = plugin,\n  on_open = function()\n    vim.notify(\"Attempting recovery.\", vim.log.levels.WARN, {\n      title = plugin,\n    })\n    local timer = vim.loop.new_timer()\n    timer:start(2000, 0, function()\n      vim.notify({ \"Fixing problem.\", \"Please wait...\" }, \"info\", {\n        title = plugin,\n        timeout = 3000,\n        on_close = function()\n          vim.notify(\"Problem solved\", nil, { title = plugin })\n          vim.notify(\"Error code 0x0395AF\", 1, { title = plugin })\n        end,\n      })\n    end)\n  end,\n})\n```\n\nYou can also use plenary's async library to avoid using callbacks:\n```lua\nlocal async = require(\"plenary.async\")\nlocal notify = require(\"notify\").async\n\nasync.run(function()\n  notify(\"Let's wait for this to close\").events.close()\n  notify(\"It closed!\")\nend)\n```\n\nSet a custom filetype to take advantage of treesitter highlighting:\n\n```lua\nvim.notify(text, \"info\", {\n  title = \"My Awesome Plugin\",\n  on_open = function(win)\n    local buf = vim.api.nvim_win_get_buf(win)\n    vim.api.nvim_buf_set_option(buf, \"filetype\", \"markdown\")\n  end,\n})\n```\n\n\nCheck out the wiki for more examples!\n\n### Viewing History\n\nIf you have [telescope.nvim](https://github.com/nvim-telescope/telescope.nvim) installed then you can use the `notify` extension to search the history:\n\n```vim\n:Telescope notify\n```\nor in lua\n```lua\nrequire('telescope').extensions.notify.notify(\u003copts\u003e)\n```\n\n**Note:** If you lazy load `telescope` you should manually call `require(\"telescope\").load_extension(\"notify\")` before using the above commands. If you don't lazy load `telescope` then `notify` does this for you.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://user-images.githubusercontent.com/24252670/136264308-2fcdfe57-a8f6-4b34-8ea1-e3a8349bc581.png\" /\u003e\n\u003c/p\u003e\n\nThere is a command to display a log of the history.\n\n```vim\n:Notifications\n```\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://user-images.githubusercontent.com/24252670/136264653-83038119-634b-48e7-8e8a-0edf4546efe2.png\" /\u003e\n\u003c/p\u003e\n\nYou can get a list of past notifications with the history function\n```lua\nrequire(\"notify\").history()\n```\n\nThere is another command to clear the history.\n\n```vim\n:NotificationsClear\n```\n\nYou can clear the notifications with the clear history function\n\n```lua\nrequire(\"notify\").clear_history()\n```\n\n## Configuration\n\n### Setup\n\nYou can optionally call the `setup` function to provide configuration options\n\nSee `:h notify.Config` for options and `:h notify.setup()` for default values.\n\n### Highlights\n\nYou can define custom highlights by supplying highlight groups for each of the levels.\nThe naming scheme follows a simple structure: `Notify\u003cupper case level name\u003e\u003csection\u003e`.\nIf you want to use custom levels, you can define the highlights for them or\nthey will follow the `INFO` highlights by default.\n\nHere are the defaults:\n\n```vim\nhighlight NotifyERRORBorder guifg=#8A1F1F\nhighlight NotifyWARNBorder guifg=#79491D\nhighlight NotifyINFOBorder guifg=#4F6752\nhighlight NotifyDEBUGBorder guifg=#8B8B8B\nhighlight NotifyTRACEBorder guifg=#4F3552\nhighlight NotifyERRORIcon guifg=#F70067\nhighlight NotifyWARNIcon guifg=#F79000\nhighlight NotifyINFOIcon guifg=#A9FF68\nhighlight NotifyDEBUGIcon guifg=#8B8B8B\nhighlight NotifyTRACEIcon guifg=#D484FF\nhighlight NotifyERRORTitle  guifg=#F70067\nhighlight NotifyWARNTitle guifg=#F79000\nhighlight NotifyINFOTitle guifg=#A9FF68\nhighlight NotifyDEBUGTitle  guifg=#8B8B8B\nhighlight NotifyTRACETitle  guifg=#D484FF\nhighlight link NotifyERRORBody Normal\nhighlight link NotifyWARNBody Normal\nhighlight link NotifyINFOBody Normal\nhighlight link NotifyDEBUGBody Normal\nhighlight link NotifyTRACEBody Normal\n```\n\n### Render Style\n\nThe appearance of the notifications can be configured, using either built-in methods or custom functions.\nSee `:help notify-render()` for details\n\n1. \"default\"\n\n![default](https://user-images.githubusercontent.com/24252670/141534868-fdcc9d03-9f7b-47fd-acfc-5a20b98e4e0a.png)\n\n2. \"minimal\"\n\n![image](https://user-images.githubusercontent.com/24252670/141534952-bb0cf491-5bb4-473c-9a67-8adb5b23b232.png)\n\n3. \"simple\"\n\n![image](https://user-images.githubusercontent.com/24252670/191683325-220208a0-90bf-4daa-b375-01b573ca524c.png)\n\n4. \"compact\"\n\n![image](https://user-images.githubusercontent.com/24252670/212632432-86621888-f885-4074-aed4-d12b5e291ab2.png)\n\n5. \"wrapped-compact\"\n\nMostly same as `compact`, but lines are wrapped based on `max_width`, some padding is added.\n\n![image](https://github.com/rcarriga/nvim-notify/assets/73286100/72237d45-6e3b-4c2a-8010-513a26871682)\n\n5. \"wrapped-default\"\n\nSimilar to `default`, but lines are wrapped based on `max_width`, some padding is added.\n\nFeel free to submit custom rendering functions to share with others!\n\n### Animation Style\n\nThe animation is designed to work in stages. The first stage is the opening of\nthe window, and all subsequent stages can changes the position or opacity of\nthe window. You can use one of the built-in styles or provide your own in the setup.\n\n1. \"fade_in_slide_out\"\n\n![fade_slide](https://user-images.githubusercontent.com/24252670/130924913-f3a61f2c-2330-4426-a787-3cd7494fccc0.gif)\n\n2. \"fade\"\n\n![fade](https://user-images.githubusercontent.com/24252670/130924911-a89bef9b-e815-4aa5-a255-84bc23dd8c8e.gif)\n\n3. \"slide\"\n\n![slide](https://user-images.githubusercontent.com/24252670/130924905-656cabfc-9eb7-4e22-b6da-8a2a1f508fa5.gif)\n\n4. \"static\"\n\n![static](https://user-images.githubusercontent.com/24252670/130924902-8c77b5a1-6d13-48f4-98a9-866e58cb76e4.gif)\n\nCustom styles can be provided by setting the config `stages` value to a list of\nfunctions.\n\nIf you create a custom style, feel free to open a PR to submit it as a built-in style!\n\n**NB.** This is a prototype API that is open to change. I am looking for\nfeedback on both issues or extra data that could be useful in creating\nanimation styles.\n\nCheck the [built-in styles](./lua/notify/stages/) to see examples\n\n#### Opening the window\n\nThe first function in the list should return a table to be provided to\n`nvim_open_win`, optionally including an extra `opacity` key which can be\nbetween 0-100.\n\nThe function is given a state table that contains the following keys:\n\n- `message: table` State of the message to be shown\n  - `width` Width of the message buffer\n  - `height` Height of the message buffer\n- `open_windows: integer[]` List of all window IDs currently showing messages\n- `buffer: integer` The buffer containing the rendered notification message.\n\nIf a notification can't be shown at the moment the function should return `nil`.\n\n#### Changing the window\n\nAll following functions should return the goal values for the window to reach from it's current point.\nThey will receive the same state object as the initial function and a second argument of the window ID.\n\nThe following fields can be returned in a table:\n- `col`\n- `row`\n- `height`\n- `width`\n- `opacity`\n\nThese can be provided as either numbers or as a table. If they are\nprovided as numbers then they will change instantly the value given.\n\nIf they are provided as a table, they will be treated as a value to animate towards.\nThis uses a dampened spring algorithm to provide a natural feel to the movement.\n\nThe table must contain the goal value as the 1st index (e.g. `{10}`)\n\nAll other values are provided with keys:\n\n- `damping: number` How motion decays over time. Values less than 1 mean the spring can overshoot.\n  - Bounds: \u003e= 0\n  - Default: 1\n- `frequency: number` How fast the spring oscillates\n  - Bounds: \u003e= 0\n  - Default: 1\n- `complete: fun(value: number): bool` Function to determine if value has reached its goal. If not\n  provided it will complete when the value rounded to 2 decimal places is equal\n  to the goal.\n\nOnce the last function has reached its goals, the window is removed.\n\nOne of the stages should also return the key `time` set to true. This is\ntreated as the stage which the notification is on a timer. The goals of this\nstage are not used to check if it is complete. The next stage will start\nonce the notification reaches its timeout.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frcarriga%2Fnvim-notify","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frcarriga%2Fnvim-notify","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frcarriga%2Fnvim-notify/lists"}