---
title: Confirmation dialogs
description: Best practices for using confirmation dialogs
---

Source: https://clickhouse.design/brand/guidelines/confirmation-dialogs

# Confirmation dialogs

Confirmation dialogs are used to prevent users from taking irreversible or dangerous actions. They add a bit of friction in exchange for safety,
by increasing the number of steps needed to complete an action.

Because it’s an extra step, the first question to ask is: *Can we avoid it?* For example, could we offer an undo option instead?
If yes, a confirmation dialog might be unnecessary. If not, we can still follow a few patterns to improve the user experience.

## Communicate at a glance

In most cases, people don’t *really* read confirmation dialogs. They’re focused on completing their task, and the dialog feels like an obstacle. That means:

- We want to minimize interaction time with the dialog
- We have a split second of attention to communicate what we need

As a result, the dialog message should be as short and clear as possible. The sections below go into more detail.

## Order of importance

When users see a dialog, they typically interact with its parts in this order:

1. **Actions** — Buttons are impossible to ignore since users *must* choose one
2. **Title** — Often read, but can be skipped if actions are obvious
3. **Description** — Often ignored

Design accordingly.

## Guidelines

### General principle

A “novice gaze” is an idea that a screen should not require prior knowledge to understand.
Picture this: a user starts an action, gets distracted by a notification, then comes back 30 minutes later to a dialog asking:
*“Do you want to do this?”* Now they have to retrace their steps to remember what “this” is. This is an example of breaking the “novice gaze”.

To maintain it:

- Avoid pronouns — name specific objects
- Use user-defined names when possible (e.g. service ‘Analytics’)

### Actions

- Use clear, specific verbs
- Match the verb used in the title
- Avoid generic verbs like *“OK”* or *“Confirm”*

### Title

- Phrase it as a question
- Use the same verb as the confirm action
- Include both the action and the target (e.g. Delete service ‘Analytics’?)
  - Place service names, organization names between single quotation marks
- Don’t overload it — be informative but concise

### Description

Since it’s often skipped, omit the description if it’s not adding extra value.
If extra context is needed to make a decision, use the description to explain the consequences, but keep it brief and scannable. One to two short sentences should suffice.

### Examples

**✅ Do:**
![
Stop data import?
Stopping an unfinished import can leave data inconsistent.
Continue import / Stop import
](./illustrations/confirm_import_do.png)

- Explicit actions
- Description explains consequences

**❌ Don’t:**
![
Cancel data import?
Are you sure you want to cancel importing data?
Cancel / Confirm
](./illustrations/confirm_import_dont.png)

- Misleading actions (does “Cancel” cancels the import or dismisses the dialog?)
- Description doesn’t add new information

**✅ Do:**
![
Delete API key ‘My key’?
All systems that use this API key will lose access to ClickHouse Cloud and will be unusable to perform their usual operations.
Cancel / Delete key
](./illustrations/confirm_apikey_do.png)

- The question is immediately clear from both actions and title
- Affected key is referenced in title
- Description explains consequences

**❌ Don’t:**
![
Your apps can lose access to ClickHouse Cloud.
If this key is used by a system, it will lose access to ClickHouse Cloud. Are you sure you want to delete this key?
Cancel / Confirm
](./illustrations/confirm_apikey_dont.png)

- Unclear question:
  - The actual action is hidden in the middle of description
  - Generic verbs
- No reference to the specific key, which key is being deleted?