Unsaved Hint
A form that holds what its server does not have yet says so. Put x-wk-unsaved on the element
around the fields, a <form> or a card, and <x-wirekit:: beside
the save button. While a field holds a value that is not saved, the field takes a light amber
line, the words "Unsaved change" stand beside its label, and the hint shows its sentence in a soft
amber badge. Saving brings all three back.
Basic Usage
The preview shows the moment after the reader changed the name. In your application the attributes
that draw it are set for you: x-wk-unsaved compares each field and marks the ones that differ.
What Counts as Unsaved
x-wk-unsaved compares each field inside it with the value the field was last saved with, at
first the one the server rendered. It tracks every field whose wire:model has no modifier that
sends the value by itself. Unlike wire:dirty, which clears as soon as a request has sent the
value, a field stays unsaved until a request saves it.
A value in another form counts as the same value. A field the reader empties over a property that
holds null is saved, and so is a number or a boolean the field holds as its text, such as "3"
for 3. A list or an object is compared entry by entry the same way.
| The field | Tracked |
|---|---|
wire:model="name" |
Yes |
wire:model.number="quantity", or any modifier that changes how the value is read |
Yes |
wire:model.blur or wire:model.change |
Yes: without .live, they only decide when the page writes the value, which then waits for the next request |
wire:model.live in any form, such as wire:model.live.blur, or wire:model.lazy |
No: the value reaches the server on its own |
| A file field | No |
Anything inside an element with data-wk-unsaved-off |
No |
A component whose wire:model sits on its own root, such as a combobox or a
multi-select, is tracked the same way. Its value lives in the
component's state rather than in the field, and that state is what is compared.
A field in a drawer or a modal counts where the dialog is
written, although the dialog is placed at the end of the page. Put x-wk-unsaved on the form inside
the dialog, and the hint in its footer, or around the dialog, and the dialog's fields and hints count
with the rest of the scope.
A request of the component that comes back without a validation error counts every field it sent
as saved. A request that comes back with a validation error saves nothing: after a save the server
refused, the fields stay framed, the hint stays, and .confirm still asks. A value the server
writes into a field itself, when it loads, resets or rewrites one, counts as saved at once.
Any request sends every deferred change with it, not only the save: a button that adds a row, a
field with wire:model.live and a poll send them too, and the fields count as saved from then on,
although nothing stored them. To count only the save itself, use
.until-saved.
Counting Only a Save
x-wk-unsaved. counts a field as saved only after a save, which is one of two things:
- a
wire:submitof the form around the field that comes back without a validation error; wirekit:saved, dispatched by the component in the request that saved.
Every other request leaves the fields unsaved, the button that adds a contact included:
<form wire:submit="save" x-wk-unsaved.until-saved.confirm>
<x-wirekit::input label="Supplier name" wire:model="name" />
<x-wirekit::button wire:click="addContact">Add a contact</x-wirekit::button>
<x-wirekit::row justify="end" gap="sm" align="center">
<x-wirekit::unsaved-hint />
<x-wirekit::button type="submit">Save</x-wirekit::button>
</x-wirekit::row>
</form>
A save that is not a wire:submit, such as a button with wire:click, says so with
wirekit:saved. Give the scope a name, and dispatch the event with that name once the save has
gone through:
<div x-wk-unsaved.until-saved="draft">
<x-wirekit::input label="Title" wire:model="title" />
<x-wirekit::row justify="end" gap="sm" align="center">
<x-wirekit::unsaved-hint />
<x-wirekit::button wire:click="storeDraft">Save draft</x-wirekit::button>
</x-wirekit::row>
</div>
public function storeDraft(): void
{
// 1. A validation error ends the action here, and the field stays unsaved
$this->validate(['title' => 'required|max:120']);
// 2. Store the title on the post this component edits
$this->post->update(['title' => $this->title]);
// 3. Count the fields of the scope named "draft" as saved
$this->dispatch('wirekit:saved', scope: 'draft');
}
What the event counts as saved depends on what it names:
wirekit:saved with |
Counts as saved |
|---|---|
scope: 'draft' |
The fields of the scope named draft |
paths: ['title', 'body'] |
The fields bound to those properties, and to every property under them: variants.3 counts variants.3.sku and variants.3.ean |
trigger: true |
The fields of the part of the page around the button whose click sent the request, or, where a key sent it, around the field with the focus: its form, else the nearest part marked data-wk-unsaved-area, else its card, else its scope |
Both scope and paths |
The fields of that scope bound to those properties |
| None of them | Every field |
trigger is for a screen of several cards, each saved by its own button. The server does not
know which button was pressed, and the page does, so the event names the button's part rather
than a scope or a path:
<div x-wk-unsaved.until-saved>
{{-- 1. Each card is the part its button saves. --}}
<x-wirekit::card>
<x-wirekit::input label="PIN" wire:model="pin" />
<x-wirekit::button wire:click="savePin">Save the PIN</x-wirekit::button>
</x-wirekit::card>
<x-wirekit::card>
<x-wirekit::input label="Opening hours" wire:model="openingHours" />
<x-wirekit::button wire:click="saveHours">Save the hours</x-wirekit::button>
</x-wirekit::card>
</div>
public function savePin(): void
{
// 1. Store the PIN of the branch this component edits
$this->branch->update(['pin' => $this->pin]);
// 2. Count the fields of the card around the pressed button as saved, and only those
$this->dispatch('wirekit:saved', trigger: true);
}
The opening hours stay unsaved although the request that saved the PIN carried them too. A part
that is neither a form nor a card, such as a row of fields in a table, takes data-wk-unsaved-area
on the element around it.
A save of several parts names each part that went through by the path above its fields, so the server lists the variants it stored rather than every field of each:
// 1. Variant 4 failed its check, so only variants 3 and 7 count as saved
$this->dispatch('wirekit:saved', paths: ['variants.3', 'variants.7']);
A dispatch of a component counts that component's fields. The page can send the event as well:
from Alpine, $dispatch('wirekit:saved', { scope: 'draft' }) counts inside the component around
the element, and from a script, an event sent to window counts on the whole page:
window.dispatchEvent(new CustomEvent('wirekit:saved', { detail: { paths: ['title'] } }));
wirekit:saved counts in a scope without .until-saved too, and also in a response with a
validation error, for a save that stored part of a form.
A Save That Did Not Go Through
A save can fail without a validation error: someone else saved the record first, or another person
holds the edit and the action is turned away. The request comes back clean, so a wire:submit under
.until-saved, or any request in a scope without it, would count the fields as saved. Dispatch
wirekit:not-saved from the component in that response, and the fields it names stay unsaved:
public function save(): void
{
// 1. Someone else saved this post since it was loaded: show the conflict and keep the fields unsaved
if ($this->post->updated_at->isAfter($this->loadedAt)) {
$this->conflict = true;
$this->dispatch('wirekit:not-saved');
return;
}
// 2. Store the post
$this->post->update(['title' => $this->title, 'body' => $this->body]);
// 3. The next save compares with the time of this one
$this->loadedAt = $this->post->updated_at;
$this->conflict = false;
}
wirekit:not-saved names its fields the way wirekit:saved does, with scope, paths (a path and
everything under it), trigger, or none of them, and it is read from the response that carries it. A value the server wrote into a field
still counts as saved, since that is what the server holds, and so does a field a wirekit:saved of
the same response names.
The Field
An unsaved field carries data-wk-unsaved, and the stylesheet draws its edge in
--color-wk-border-unsaved: one line of the light warning color, and nothing else, no ring and no
fill. Unsaved is a hint, not a fault, and a strong frame reads like a field that was refused. What
the line means stands beside the field's label, small (--text-wk-xs) and in the muted text color:
"Unsaved change", in the reader's language. The words sit in the line of the label, so nothing
below the field moves while the reader types.
A field with a prefix, a clear button or pills draws the line on the frame around them. Under a
theme whose border width is 0px, such as the Material and Minimal presets, the line is drawn
inside the field, at least 1px. It takes no room, so the field does not move when it changes,
and the field's focus ring stays as it is. An invalid field keeps its error border, and its label
takes no words, since the error comes first:
Enter a complete email address.
Checkboxes, Radios and Switches
A checkbox, a radio or a switch shows its value as a fill or a position, so an edge in the unsaved
color would hide it. It takes a line of 1px around its box or its track instead, clear of its own
edge, in the same color. Both radios of a changed choice take it, because the choice is the field.
A single checkbox or switch also takes the words beside its label; the options of a choice and the
checkboxes of a list do not, since every option would say them. While the keyboard has the focus on
the control, its focus ring takes the place of the line, and an invalid control takes none:
What the Colors Say
A success is green, a warning and an unsaved value are amber, and an error is red. Information
takes the accent until your theme gives it a hue of its own, see
Giving info a color of its own. To mark unsaved values
in another color, set --color-wk-border-unsaved on :root and on .dark. The light line is not
held at 3:1 against the page, since the words beside the label say what it means; set the token to
var(--color-wk-warning-text) for a line at 3:1 and more. The hint's badge is the soft warning
badge and takes the warning color of your theme.
The scope carries data-wk-has-unsaved while any field in it is unsaved, for a style of your own,
such as a save button that stands out:
[data-wk-has-unsaved] .save-button {
box-shadow: 0 0 0 2px var(--color-wk-border-unsaved);
}
The Words Beside the Label
The words come from the hint, in the reader's language, under the translation key
wirekit::, which your own catalog can word differently. A scope without a hint
writes them in English. To give a scope words of its own, set data-wk-unsaved-words on it, and
set it empty to show none:
<form wire:submit="save" x-wk-unsaved data-wk-unsaved-words="{{ __('Not saved yet') }}">
The words need a <label> that names the field, as every WireKit field renders one from its
label prop. A field without a label of its own takes only the line.
The words never move the field and never run out of their label. In a narrow column, or beside a long label in another language, they would wrap onto a line of their own and push the field down, or, where the label's last word stands alone on its line, run past the label's edge, so WireKit measures each label where it stands and shows less: a dot in the color of the line, with the words as the label's title, and where even the dot does not fit, nothing, and the line says it alone. A label that does not stand above its field, the one around a switch or a single checkbox, takes no words either, since words in its line would push what stands beside it. The labels are measured again whenever the window takes a new width.
The field names the same words in its description as well, so a screen reader that comes to the field hears "Unsaved change" after its name and the description it already had, its help text for one. The description points at a hidden element WireKit adds to the page for that, and leaves the field once it counts as saved. A radio button and a checkbox of a list are not described, as they take no words, and neither is an invalid field, whose error comes first.
Asking Before the Reader Leaves
x-wk-unsaved. asks before the page is left with an unsaved field. A reload, a closed tab and
a typed address get the browser's own question, in the browser's words, which no page can replace.
A wire:navigate link and an ordinary link to another page of the same site get the hint's
question instead, in the reader's language, in an alert dialog the
hint brings with it. That dialog closes through its own answers, so
components. set to true, the default for your own alert dialogs,
does not reach it. Stay has the focus and keeps the page and everything typed into it, and so
does Escape; the link the reader pressed has the focus again afterwards. Leave goes on to the
link's page without asking again, and the browser does not ask either. That holds for this one
visit: a link that answers with a download or with no content leaves the reader on the page, and
the next reload, closed tab or link asks again. A step back or forward through the history is not
held.
An ordinary link asks only when it leaves for another page in the same window: pressed with the main
button and no key held, without download and without a target of another window (_top and
_parent name this one on a page no frame holds), on the same site, and to another path or query
than the page's own. A link without a target of its own takes the one of the page's <base>, as
the browser does, so under <base target="_blank"> it opens a new window and asks nothing. Every
other link is left to the browser, a link to a fragment of the page included.
<form wire:submit="save" x-wk-unsaved.confirm>
<x-wirekit::input label="Supplier name" wire:model="name" />
<x-wirekit::row justify="end" gap="sm" align="center">
<x-wirekit::unsaved-hint />
<x-wirekit::button type="submit">Save</x-wirekit::button>
</x-wirekit::row>
</form>
Under the question the dialog lists what is unsaved: up to five fields, each named by its label, a
group of radios or checkboxes by the caption of its legend, and placed by what stands around it, the tab of a tabs panel, the heading of a
card, the title of an accordion item and the name of a
part marked data-wk-unsaved-area="Opening hours", and a line with the number of the others. The
fields of one place stand together in a box headed "Section: General", each as "Unsaved content:
Title", and a field around which nothing names a place stands outside every box. Each
entry is a button. It closes the dialog and keeps the page, as Stay does, opens the tab, the
accordion item, the collapsible card and every closed details around its field, and gives the
field the focus.
A save that redirects does not ask: the response is weighed before the redirect runs, so its fields
count as saved by then. The two answers are the translation keys wirekit::Stay and
wirekit::Leave, which your own catalog can word differently, as Localization shows.
The line under the list is wirekit::{1} and :count more field|[2,*] and :count more fields, and
the two labels of the list are wirekit:: and wirekit::.
Saying What Leaving Does
Leave throws away what is unsaved, unless your application keeps it, as a draft of the record for
instance. Only the page knows which at the moment it asks, so the scope dispatches
wirekit:unsaved-question just before the dialog opens, bubbling, and what a listener sets in the
event's detail is what the dialog says at this opening:
| Key | Default | What it sets |
|---|---|---|
question |
the scope's question | The dialog's title |
description |
none | A sentence under the title, which also describes the dialog for a screen reader |
leave |
"Leave" | The label of Leave |
shortcut |
false |
Whether ⌘↵ or Ctrl+Enter presses Leave |
fields |
What is unsaved, each { name, place }, to decide by |
// 1. A form whose fields your application keeps as a draft carries `data-keeps-draft`.
document.addEventListener('wirekit:unsaved-question', (event) => {
if (event.target.closest('[data-keeps-draft]')) {
event.detail.description = 'What you have not saved stays as a draft of the record.';
event.detail.leave = 'Leave page';
// 2. Leaving loses nothing here, so the shortcut may press Leave.
event.detail.shortcut = true;
} else {
event.detail.description = 'What you have not saved is lost.';
event.detail.leave = 'Discard and leave';
}
});
The event's target is the scope that asks. A value that is not text keeps its default, and the next
opening starts from the defaults again. Without shortcut, ⌘↵ and Ctrl+Enter press nothing in this
dialog, since Leave throws away what the reader typed.
A page that asks in its own way, a bar of tabs that asks before it closes one, sends
wirekit:unsaved-release to window once its own question is answered, and nothing asks again
until the next page. It hears wirekit:unsaved on window whenever the page gains its first
unsaved field or loses its last, with unsaved in the event's detail:
// 1. Know whether closing the tab loses anything.
let holdsUnsaved = false;
window.addEventListener('wirekit:unsaved', (event) => {
holdsUnsaved = event.detail.unsaved;
});
// 2. The tab bar asked the reader itself: the page asks nothing more on the way out.
window.dispatchEvent(new CustomEvent('wirekit:unsaved-release'));
A scope without a hint of its own asks in the dialog of a hint elsewhere on the page, in English unless it names its own question. On a page without any hint, the browser's own question asks instead:
<div x-wk-unsaved.confirm data-wk-unsaved-confirm="{{ __('Discard the changes to this supplier?') }}">
Your Own Sentence
text replaces the sentence, and the slot replaces it with markup:
The Directive
x-wk-unsaved takes two modifiers, which combine (x-wk-unsaved.), and an
optional name:
| Directive | On | Does |
|---|---|---|
x-wk-unsaved |
the element around the fields | Marks each unsaved field with data-wk-unsaved and its label with data-wk-unsaved-note, itself with data-wk-has-unsaved, and shows the hints inside it |
x-wk-unsaved.confirm |
the same element | Also asks before the page is left with an unsaved field |
x-wk-unsaved.until-saved |
the same element | Counts a field as saved only after a wire:submit of its form or a wirekit:saved |
x-wk-unsaved="draft" |
the same element | Names the scope, for wirekit:saved with scope: 'draft'. The name is read as written, not evaluated |
data-wk-unsaved-area |
an element inside the scope | Marks the part one button saves, for wirekit:saved with trigger: true, where that part is neither a form nor a card. A value names the part in the question before leaving |
Props
| Prop | Type | Default | Description |
|---|---|---|---|
text |
string|null | null |
The sentence shown while a field in the scope is unsaved. Without it the hint reads "Unsaved changes", in the reader's language |
question |
string|null | null |
What x-wk-unsaved.confirm asks before a wire:navigate visit. Without it: "You have unsaved changes. Leave this page anyway?", in the reader's language |
scope |
string|null | null |
Scoped personalization name |
Accessibility
- The hint is a polite live region (
role="status") that is always in the page. When the first field becomes unsaved, its sentence is written again, so a screen reader announces it once; it says nothing when a save clears it. - While nothing is unsaved, the hint takes no room and its sentence is out of the accessibility tree, so a screen reader does not find a stale "Unsaved changes" in the page.
- The line of an unsaved field is not the only sign of it: the words beside the label and the hint's sentence say what it shows (WCAG 1.4.1). For that reason the light line is not held at 3:1 (WCAG 1.4.11): the state is told by the words, and a field that holds a value is told by that value and its label. Set
--color-wk-border-unsavedtovar(--color-wk-warning-text)for a line at 3:1 and more. - The words beside the label stay out of the field's accessible name, which remains its label: the stylesheet writes them with an empty alternative text. Safari before 17.4 does not know that syntax and reads them with the label, which then says the field is unsaved.
- The same words are the field's description while it is unsaved (
aria-describedby, after any description it had), so a screen reader says on the field itself which one is not saved, where the hint says only that one is. - The hint's badge carries no symbol: its sentence says in words what it means.
- The line around an unsaved checkbox, radio or switch gives way to the focus ring while the keyboard has the focus on the control, so the focus stays visible (WCAG 2.4.7).
Keyboard Interaction
The hint takes no focus and has nothing to operate: it is a sentence. The fields around it keep their own keys, and nothing about the keyboard changes when a field turns unsaved. With .confirm, the question before a wire:navigate visit or an ordinary link is an alert dialog: it opens with the focus on Stay, Tab reaches Leave and the entries of the list, Enter or Space answers with the focused button, and Escape stays. After Stay or Escape the focus is back on the link that asked.
Pitfalls
- The hint belongs inside the scope. A hint outside any
x-wk-unsavedstays hidden. - Without
.until-saved, any request that comes back without a validation error counts as saving. See What Counts as Unsaved: a field withwire:model.livein the same component makes the others count as saved with every request it sends..until-savedwaits for the save. - A save that fails without a validation error looks like one that went through. A conflict or a refused action that only shows a toast leaves no error in the response, so a scope without
.until-saved, or awire:submitunder it, counts the fields as saved. Dispatchwirekit:not-savedin that response, see A Save That Did Not Go Through, or put the reason into the error bag where it belongs to a field,$this->add, and they stay unsaved.Error('title', __('Someone else saved this post first.')) - Under
.until-saved, a save withoutwire:submitneedswirekit:saved. Without the event the fields stay unsaved after the save, and.confirmasks before the redirect that follows it. - A browser asks a reload in its own words. The text of that question cannot be set by a page;
questionreaches thewire:navigatecase only.
Design Tokens
| Token | Used for |
|---|---|
--color-wk-border-unsaved |
The line of an unsaved field or of its frame, and the line around an unsaved checkbox, radio or switch. By default the light warning color |
--color-wk-text-muted |
The words beside the label of an unsaved field |
--color-wk-warning |
The tint of the hint's badge |
--color-wk-warning-text |
The hint's sentence |
--text-wk-sm |
The sentence's size |
--font-wk-sans |
The sentence's font |