Edit
Change an existing thing.
Edit covers changing something that already exists, from fixing a typo in a comment to reworking an organization's settings across a dozen fields.
Where this happens
- Edit a comment on an issue
- Edit a file from the code view
- Change basic profile details
- Edit a repository variable
- Rename a branch in a repository
See all edit scenarios in the Scenarios repo (GitHub staff only).
Implementation guidelines
-
Use FormControl for each editable field, Dialog when an edit needs someone's full attention, and a full-page form for settings that span several sections.
-
Use
PencilIconon IconButton edit triggers, and give each one a name that identifies its target, following descriptive button naming. -
Label the save button with a verb that names what will change. Show a loading state while the save runs, and place the button adjacent to the input when the edit happens in place. See the saving pattern's button text guidance.
-
Validate on submit and tie each error message to its field, following form validation guidance, and show a failed save in place with a Banner
variant="critical"or an InlineMessage. Move focus to the first invalid field, or to the message when no single field is at fault. -
When a save needs a separate confirmation, place it next to the control that triggered it rather than at the top of the page, following Notification messaging.
-
Manage focus when an edit surface opens and closes. Move it into the field for an inline edit, leave Dialog to place its own, and return it to the trigger on close.
-
When an edit surface has a sticky save bar or floating toolbar, keep it clear of the field that has focus, so people can see what they're editing.
-
Warn before navigating away from or closing an edit someone has started, following the saving pattern's unsaved changes guidance.
User experience principles
Match the surface to the scope of the edit
Reach for the lightest surface that still gives the edit enough room: in place next to the content, a dialog over it, or a dedicated page. Weigh consequence alongside scope, because changing one field can change other things at the same time. This choice also sets the save behavior, the feedback, and where the trigger goes, so make it first.
Edit a single field in place, use a dialog when the edit needs someone's full attention, and use a full page for settings that span several sections.
Send someone to a separate settings page to change one line of text.
Preview what else an edit will affect before someone confirms it, like renaming a branch that retargets its open pull requests, and offer a way to undo it afterward. See error forgiveness.
Treat an edit as routine because it changes one field, when saving it also changes other things in the repository.
Show people how their rich text will look while they write it, so they don't have to switch away to check.
Make a preview mode the only way to check formatting, especially when switching to it costs people their place in the text.
Put the edit next to what it changes
Proximity makes an edit discoverable and shows what it affects. An edit that belongs to one visible thing should be reachable from that thing, while an edit that spans a whole resource belongs on its settings page.
Put the trigger next to the content it edits, and show it only to people who can use it.
Show an edit trigger to someone who doesn't have permission to use it, so they only find that out after clicking.
Keep the edit trigger visible, or reveal it on keyboard focus as well as hover, so it's reachable without a pointer.
Reveal the edit trigger on hover alone, which puts it out of reach on touch and for anyone using a keyboard.
Allow one edit open at a time on a page where people can edit several things separately, following the saving pattern's save button placement guidance.
Open several editors at once, leaving a page of identical save buttons that give no clue which change each one saves.
Name what's being saved
A label that names the thing it changes makes sense on its own. That helps anyone scanning a page full of buttons, and matters most for screen reader users. They can list every button on the page and hear each label with none of the surrounding context to explain it.
Label the save action with an active verb and the thing it changes, like "Update comment", when a page has more than one save action. A plain "Save changes" is enough when there's only one thing to save.
Use "Done", "OK", or "Submit". At best they name the act of saving, never the thing it changes.
Default to explicit save
An explicit save lets people check a change before they apply it, and stops a change happening by accident. That matters most for anyone moving through a set of options with a keyboard or a screen reader, where reading the choices shouldn't apply them. Editing nearly always involves content someone authored or configured, so an explicit save is the default here. Save on selection only for imperative controls, where choosing is itself the action.
Use an explicit save for anything someone authored or configured.
Save declarative controls like text inputs, radio groups, and selects automatically as they change.
Apply the change immediately for a single obvious toggle, like marking a notification as read, in line with imperative controls.
Mix automatic and explicit saving in one form, so it's unclear which changes are already applied.
Save on Enter in a single-line editor, and give a multi-line editor its own save control.
Bind Enter to save in a multi-line editor, where people expect it to start a new line.
Keep the save button enabled even when the form is unchanged or invalid, following the button state guidance, so people can submit and find out what needs fixing.
Disable the save button based on form state. A disabled button can't take focus and its label is hard to read.
Let people cancel an edit
People start edits by accident, misjudge what they meant to change, or change their mind partway through. Where the only way out is to save and then undo, or to reload the page, they're left with a change they didn't want. Every edit surface needs a visible cancel that restores the previous value, and a confirmation before discarding work worth keeping.
Give every edit surface a visible cancel alongside the save button, and cancel on Escape as well, returning focus to the trigger to match the Escape behavior of dialogs and overlays.
Make Escape or a click outside the only way to abandon an edit, which leaves nothing to tap on a touch device.
Put the content back to the value it had before the edit when someone cancels.
Close the editor on cancel while keeping the typed change, so cancel and save do the same thing.
Confirm before discarding an edit someone has put work into, using ConfirmationDialog, and skip the prompt when they haven't typed anything.
Discard a half-written edit because someone pressed Escape or clicked outside the editor.
Make it clear when changes are saved
People who can't tell whether an edit saved assume it didn't, and some draft in another tool rather than risk losing work on GitHub. Show that an edit saved without anyone having to reload the page to check. The timing follows the save method: an explicit save confirms once when it runs, covering every change together, while a control that applies on selection confirms as soon as it's chosen.
Show the updated content as the confirmation, and add a separate message only when the result isn't visible, like a setting that takes effect further down the page.
Rely on the editor closing as the only signal. It communicates nothing to someone using a screen reader.
Protect work when a save fails
When a save fails, keep the draft and tell the person enough to fix it without guessing. This covers work lost to an accidental refresh or to someone else saving first, not only work lost to a failed request.
Keep the editor open and the fields filled when a save fails, with the error next to whatever caused it.
Discard what someone typed, or replace the page with a generic failure message they can't act on.
Where losing work would be costly, like a code or wiki editor, keep a local draft so edits survive an accidental refresh.
Reopen the editor empty after someone navigates back to it.
For content several people can edit, check whether it changed while someone was working on it and show them the conflict before their save overwrites it.
Silently overwrite someone else's change, so neither person knows the first edit is gone.