{"id":28231307,"url":"https://github.com/ajanibilby/hx-keep","last_synced_at":"2026-03-04T09:31:03.379Z","repository":{"id":289988771,"uuid":"973057401","full_name":"AjaniBilby/hx-keep","owner":"AjaniBilby","description":"keep htmx client state across page refreshes","archived":false,"fork":false,"pushed_at":"2025-05-12T01:44:32.000Z","size":206,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-29T07:28:01.172Z","etag":null,"topics":["cache","client","form","htmx","local-storage"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/hx-keep","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/AjaniBilby.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-04-26T06:54:03.000Z","updated_at":"2025-08-05T14:54:46.000Z","dependencies_parsed_at":"2025-04-26T07:07:22.970Z","dependency_job_id":"6d4a16db-e77d-4f6b-b947-7b627ec5dcf8","html_url":"https://github.com/AjaniBilby/hx-keep","commit_stats":null,"previous_names":["ajanibilby/hx-keep"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/AjaniBilby/hx-keep","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AjaniBilby%2Fhx-keep","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AjaniBilby%2Fhx-keep/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AjaniBilby%2Fhx-keep/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AjaniBilby%2Fhx-keep/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AjaniBilby","download_url":"https://codeload.github.com/AjaniBilby/hx-keep/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AjaniBilby%2Fhx-keep/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30077064,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-04T08:01:56.766Z","status":"ssl_error","status_checked_at":"2026-03-04T08:00:42.919Z","response_time":59,"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":["cache","client","form","htmx","local-storage"],"created_at":"2025-05-18T19:09:32.497Z","updated_at":"2026-03-04T09:31:03.364Z","avatar_url":"https://github.com/AjaniBilby.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"Keep your htmx client state persistent across refreshes, new windows, and re-opening of your pages - as simple as:\n\n```html\n\u003cdiv id=\"logs\" hx-keep=\"first 3\"\u003e...\u003c/div\u003e\n\u003cform id=\"my-form\" hx-keep=\"form\"\u003e...\u003c/form\u003e\n```\n\n![banner](/images/banner.gif)\n\nWe also include bindings to allow client side code to read/write into the `hx-page` data for custom form elements, see [examples](/example/).\n\n## Getting Started\n\n### CDN\n\n```html\n\u003cscript src=\"https://unpkg.com/hx-keep@1.1.1\"\u003e\u003c/script\u003e\n```\n\n### Bundle\n\nTo bundle in an npm-style build system with ES modules, you will have to add `htmx` to the `document` like so:\n\n```\nnpm i hx-drag\n```\n\n```javascript\n// index.js\nimport \"./htmx\";\nimport \"hx-keep\";\n```\n\n```javascript\n// htmx.js\nimport htmx from \"htmx.org\";\nwindow.htmx = htmx; // to support hx-drag\nexport default htmx;\n```\n\n### Enable\n\n```html\n\u003cbody hx-ext=\"hx-keep\"\u003e...\u003c/body\u003e\n```\n\n---\n\n## HTML Attributes\n\nAll html attributes can have the `data-` prefix if required by your framework.\n\n### `hx-keep=\"{mode}\"`\n\nThis attribute specifies which data to store and restore from based on the mode set\n\n| Mode | Description |\n| :- | :- |\n| `innerHTML` | Will keep the entire outer html of the element\n| `outerHTML` | Will keep only the inner html of the element\n| `first x` | Will keep only the first `x` elements inside the main element. To prevent cutting in weird places we recommend wrapping items in a `\u003cdiv style=\"display:contents;\"\u003e` so you can control where it cuts.\n| `last x` | Same as `first` but takes the last elements\n| `form`  | Tracks and restores only the form values, rather than the entire html\n\nIf you want to cache only a single input, we recommend wrapping it in a:\n```html\n\u003cform id=\"form\" style=\"display: contents\" hx-keep=\"form\"\u003e\u003cinput name=\"myValue\"\u003e\u003c/input\u003e\u003c/form\u003e\n```\n\n### `hx-keep-key`\n\nUsed to tell `hx-keep` how to identify the element, especially useful if it is shared across multiple urls or locations.\n\nIf the key is not specified, `hx-keep` will assume the key is `${url.pathname}#${element.id}`.\nIf both the key and id are not specified on the element, then the whole element will be ignored.\n\n### `hx-keep-hash`\n\nThe hash is just a simple string value, and if the hash on the element, and the hash of the stored data do not match, then the element will not be restored. This can be helpful if you want to ensure content from an old format is not being restored into a new layout when you update your site.\n\nYou could also use this as a date-stamp, so if the underlying data in a form changes it throws away the client cached form.\n\n### `hx-keep-restore=\"off\"`\n\nIf set to `off`, then `hx-keep` will not restore, however it will still save when changes are made.\nThis can be helpful if on a specific load you want it to not restore from cache, and instead override with the server's contents.\n\n### `hx-keep-evict`\n\nIdentical behaviour to the [`HX-Keep-Evict`](#response-hx-keep-evict) header, however you can also include the value directly in any element for it to take affect when mounted by htmx.\n\n### `hx-keep-expiry`\n\nHow long until the value should be cleared from local storage? Defaults to 30 minutes if unspecified.\nThis must be an integer value with a postfix for the units.\n\n| Postfix | Description |\n| `s` | Seconds (i.e. `30s`) |\n| `h` | Hours |\n| `d` | Days |\n\n\u003e Note: `hx-keep` will not automatically clear the data as soon as they expire, it will only prune data when a window is started\n\n### `hx-history=\"false\"`\n\nThis library will respect [hx-history](https://htmx.org/attributes/hx-history/), and omit any inputs or elements with this attribute when saving it's data.\n\n---\n\n## CSS Classes\n\n### `hx-keep`\n\nIf an element has this class if means it is being cached by `hx-keep` and does not match what the server originally sent.\n\nIn the case of a `hx-keep=\"form\"`, this class will update as the form values are changed allowing for save state indicators based on whether the input is actually different from what was originally served.\n\n---\n\n## Http Headers\n\n### Request: `HX-Keep-Key`\n\nIf a htmx request is triggered from an element with a `hx-keep-key`, that value will be included in the request sent to the server.\nThis is helpful in combination with the [hx-keep-evict header](#response-hx-keep-evict) to clear a value from `hx-keep` after it has been submitted to the server.\n\n### Request: `HX-Keep-Hash`\n\nSimilar to [`HX-Keep-Key`](#request-hx-keep-key), but instead will include the `hx-keep-hash` value as a http header.\n\n### Response: `HX-Keep-Evict`\n\nWhen a response with this header is received by the client, it will evict all `hx-keep` data where the key matches the pattern(s) supplied. This occurs before rendering meaning these values will be gone before any potential restoration by `hx-keep`.\n\n\u003e The patterns are comma separated and then have their whitespace trimmed before matching.\n\nThere is only one type of wildcard supported which is the `*` which matches with zero to many characters (i.e. `/logs/*/short/*`).\n\n---\n\n## JS API\n\n### Context\n\n### Get\n\n```ts\nwindow.hx_keep.getValue = (ctx: Element | string | null, name: string): string | null;\n```\n\nGoing from the provided element it will find the `hx-keep` form it is within, then return the value in the form.\n\n### Set\n\n```ts\nwindow.hx_keep.setValue = (ctx: Element | string | null, name: string, value: string, expiry?: number): void;\n```\n\nWill go from the provided element and find the relevant `hx-keep` form, then set the provided form value.\nIt will also change the expiry if provided (time from now in milliseconds).\n\nIf expiry is unspecified it will continue with the currently expiry for the key. However when specified it must be measured in seconds from now.\n\n### Get Form\n\nSame as [`getValue()`](#get) but returns the whole form as `Record\u003cstring, string\u003e`\n\n### Set Form\n\nSame as [`setValue()`](#set) but takes the whole form as `Record\u003cstring, string\u003e`\n\n### Evict\n\n```ts\nwindow.hx_keep.set = (pattern: string[] | string) =\u003e void;\n```\n\nWill delete the `hx-keep` entries which have the keys that match the pattern(s) given.\n\nThe patterns can use `*` to signify zero-many characters (i.e. `/logs/*/short/*`).\n\n### Prune\n\n```ts\nwindow.hx_keep.prune = () =\u003e void;\n```\n\nThis will delete all of the expires entries.\n\n### Shrink\n\n```ts\nwindow.hx_keep.shrink = () =\u003e void;\n```\n\nWill `prune()`, if no entries are removed it will delete the oldest one.\nThis is useful if you have ran out of [`localStorage` capacity](https://developer.mozilla.org/en-US/docs/Web/API/Storage_API/Storage_quotas_and_eviction_criteria#web_storage)\n\n### Clear\n\n```ts\nwindow.hx_keep.clear = () =\u003e void;\n```\n\nDeletes all `hx-keep` data, this is useful for ensuring all data is removed on logout.\nThough you could also use a [http `hx-keep-evict: *` header](#response-hx-keep-evict) for this purpose\n\n### Is Saved\n\n```ts\nwindow.hx_keep.isSaved = (ctx: Element | null): boolean;\n```\n\nReturns if the `hx-prep` context is different from the original server content or not\n\n---\n\n## Examples\n\nSee [https://hx-keep.ajanibilby.com/example](https://hx-keep.ajanibilby.com/example)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fajanibilby%2Fhx-keep","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fajanibilby%2Fhx-keep","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fajanibilby%2Fhx-keep/lists"}