Delete

Delete an existing thing. Remove it permanently, or disassociate it from something.

Delete covers permanently destroying a resource or disassociating it from a context. It runs from high-stakes and irreversible, like deleting a repository, to routine, like removing a label from an issue. How much friction to put in someone's way depends on how much damage a mistake would do.

Where this happens

See all delete scenarios in the Scenarios repo (GitHub staff only).

Implementation guidelines

Use ConfirmationDialog for most delete confirmations. It has built-in focus management and sets role="alertdialog" automatically. For type-to-confirm flows that need a text input, use Dialog instead, but you'll need to handle returnFocusRef manually.
Use ActionList.Item variant="danger" for delete options in menus and action lists. This applies danger styling through the theme rather than CSS classes. TrashIcon is the standard leading visual.
Use Button variant="danger" for the confirm button, and pair the color with a clear text label, like "Delete repository", so the destructive intent doesn't rely on color alone.
Show a loading state on the confirm button when the deletion is likely to take more than a moment, so people know their action registered.
When deletion removes the current page's primary resource, redirect to the parent page, like the list or container the item belonged to.
When deletion happens in place and removes the focused item or the control that opened the dialog, set focus instead of letting it fall back to the page. Prefer the previous equivalent control because it keeps people near known context. If there isn't one, move focus to the grouping container, list heading, or another stable parent with a useful accessible name and role.
Don't add a visible success banner by default. The item disappearing or the redirect is usually signal enough, in line with notification messaging guidance. Always announce the result to screen readers through a live region. See Accessible notifications and messages.
When a deletion fails, keep the dialog open and show a Banner variant="critical" inside it so people can retry without losing context. See notification messaging.

User experience principles

Match friction to the cost of a mistake

Too much friction slows people down and trains them to click through every warning. Too little risks data loss they can't undo.

Place high-impact deletions in a danger zone within settings, and keep low-impact deletions inline or in a contextual menu.

Don’t

Surface every delete action in the same place, with the same weight, regardless of how much damage a mistake would do.

Match the amount of friction to the blast radius. Use type-to-confirm for org-wide or repo-wide impact, a simple dialog for single resources, and no confirmation for reversible actions.

Don’t

Use the same confirmation dialog for "remove item from project" (reversible) and "delete project" (permanent).

Reserve type-to-confirm for irreversible actions with wide blast radius, so the extra friction still means something when people hit it.

Don’t

Wrap a routine reversible action, like removing a label, in a confirmation dialog. People learn to click through and stop reading.

Prefer reversibility over confirmation

An undo protects someone who makes a mistake without interrupting someone who doesn't. A confirmation dialog interrupts everyone, and people dismiss it out of habit.

Offer an undo window for actions you can reverse, instead of a prompt that blocks everyone up front.

Don’t

Gate a low-stakes, recoverable action behind a confirmation dialog when a brief undo would do the same job.

For high-value resources with dependencies, offer a reversible "Disable" step alongside permanent "Delete".

Don’t

Jump straight to permanent deletion when a reversible alternative would serve the user's intent.

Make the consequences clear before committing

Show what gets deleted and whether it can be recovered. Match the wording to what actually happens.

Name what's affected and whether it's permanent, like "Delete label?" with a line on what gets removed.

Don’t

Fall back on a generic "Are you sure?" that hides what's about to happen.

Label the confirm button with the action, like "Delete repository", so it reads clearly out of context. Keep it to a few words, in line with the ConfirmationDialog guidelines.

Don’t

Use "Yes", "OK", or "Confirm". They don't say what happens. The one exception is type-to-confirm, where a fuller phrase like "I understand, delete this project" is deliberate.

Say "Remove" when the thing still exists elsewhere, and "Delete" when it's permanently destroyed.

Don’t

Say "Delete" for an action that only disassociates. The wording promises more than it does.