@gemeente-denhaag/modal

中文文档
3.2.0发布于 2026/10/05EUPL-1.2TypeScriptESM + CJS构建来源已验证近 30 天下载 3639

The Modal component

原始使用文档
文档目录20 节
  1. When to use
  2. Alternatives and related components
  3. Anatomy
  4. (Interactive) states
  5. Design properties
  6. Typography
  7. Colors
  8. Button
  9. Structure
  10. Accessibility
  11. Error alerts in forms
  12. Content guidelines
  13. Title
  14. Body content
  15. Primary and secondary actions
  16. Best practices
  17. Dos
  18. Don’ts
  19. Javascript
  20. References

Modal

npm version

Modals are overlays that prevent users from interacting with the rest of the application until a specific action is taken.

When to use

Use a modal to request information that is preventing the system from continuing a user-initiated process. It can also be used to notify the user of urgent information concerning their current work. Modal dialogs are commonly used to report system errors or convey a consequence of a user’s action. Finally, it can be used to confirm user decisions. Clearly describe the action being confirmed and explain any potential consequences that it may cause. Both the title and the button should reflect the action that will occur.

  • Use an accordion to present large amounts of additional information or actions that don’t require confirmation
  • Use a banner to communicate a change or condition that needs the users attention within the context of a page

Anatomy

The modal consists of:

  1. Title: gives users a quick overview of the modal.
  2. Close icon: closes the modal.
  3. Text: contains the information needed to complete the modal’s task. It can include message text and components.
  4. Buttons (optional): button that allows users to perform an action or close the modal.
  5. Overlay: screen overlay that obscures the on-page content.

(Interactive) states

None.

Design properties

Typography

  • Title: TheMix/xl/700
  • Text: TheSans/md/400

Colors

  • Title: text color Blue/3
  • Close icon: svg color Grey/4
  • Text: text color Grey/4
  • Overlay: background-color white

Button

The buttons text only, medium primary and secundary are used.

Structure

  • Title: padding-top and padding-left 32px, margin-bottom 16px
  • Close icon: height and width 24px, padding-right 32px
  • Text: padding-left and padding-right 32px, margin-bottom 48px
  • Buttons: padding-right and padding-bottom 32px, padding space between buttons 16px

Accessibility

[technical accessibility requirements]

Error alerts in forms

Error alerts

If users submit long or complex forms with errors, use an error alert to summarize what went wrong. Place the alert at the top of the form and move the focus to the banner when the form is submitted. This will allow all users to scroll through the form in a logical order to resolve the issues.

Inline errors

Always include inline error messages for specific form fields so that users know what to do in context while correcting their errors.

Content guidelines

Title

Modal titles should:

  • Use a clear {verb}+{noun} question or statement.

Body content

Body content should be:

  • Actionable: start sentences with imperative verbs when telling an user what actions are available to them (especially something new). Don’t use permissive language like "you can".

  • Structured for users success: always put the most critical information first.

  • Clear: use the verb “need” to help users understand when they’re required to do something.

Primary and secondary actions

Actions should be:

  • Clear and predictable: users should be able to anticipate what will happen when they click a button. Never deceive a user by mislabeling an action.
  • Action-led: actions should always lead with a strong verb that encourages action. To provide enough context to users use the {verb}+{noun} format on actions except in the case of common actions like Save, Close, Cancel, or OK.
  • Scannable: avoid unnecessary words and articles such as the, an, or a.

Best practices

Dos

Use modals when users must complete an action before they can continue with the main workflow. Avoid using modals to display complex forms or large amounts of information.

Modals should:

  • Require that users take an action.
  • Close when users press the X button, the Cancel button, or the ESC key, not when users click or tap the area outside the modal.
  • Be used very sparingly.
  • Be used for important warnings, as a way to prevent or correct critical errors.
  • Be used to request the user to enter information critical to continuing the current process.
  • Notify the user after the action that has been taken.

Don’ts

Modals should:

  • Not be used for nonessential information that is not related to the current user flow.
  • Not have more than two buttons (primary and secondary) at the bottom. This prevents unclear action hierarchy and crowding on mobile screens. Since modals are for focused tasks, they should have focused actions.
  • Not be closable when the users click or tap the area outside the modal.
  • Not include multiple steps.
  • Not cram in too much.
  • Not include important information.
  • Not open suddenly. A modal should always open upon the user doing (or did) something.

Javascript

Import the @gemeente-denhaag/modal/src/modal.js javascript file to you site to allow the modals to work.

See the example below:

import ModalScripts from "@gemeente-denhaag/modal/src/modal";
window.addEventListener("DOMContentLoaded", () => new ModalScripts());

References

Figma Design http://www.uxforthemasses.com/overlays/ https://www.nngroup.com/articles/modal-nonmodal-dialog/

版本与发布记录

@gemeente-denhaag/modal 共发布 361 个版本,首次发布于 2022/01/24;过去 12 个月发布了 9 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
3.2.0latest2026/10/051 个月前
3.1.42026/09/231 个月前
3.1.32026/08/272 个月前
3.1.22026/08/182 个月前
3.1.12026/07/273 个月前
3.1.02026/06/294 个月前

关于 @gemeente-denhaag/modal 的常见问题

@gemeente-denhaag/modal 是什么?

The Modal component

如何安装 @gemeente-denhaag/modal?

在项目目录运行 npm install @gemeente-denhaag/modal,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:react(18 || 19)、react-dom(18 || 19)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@gemeente-denhaag/modal 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@gemeente-denhaag/modal 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@gemeente-denhaag/modal 可以商用吗?

@gemeente-denhaag/modal 使用 EUPL-1.2 许可。声明的许可为 EUPL-1.2,请阅读许可原文确认使用条件。以上为概括,不构成法律意见,请以许可原文为准。

@gemeente-denhaag/modal 的下载量有多少?

根据 npm 官方下载统计,@gemeente-denhaag/modal 在 2026/10/16 – 2026/11/14 这 30 天内被下载 3,639 次,日均约 121 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gemeente-denhaag/modal 还在维护吗?

最新版本 3.2.0 发布于 2026/10/05(1 个月前);至今共发布 361 个版本,其中过去 12 个月发布了 9 个;首次发布于 2022/01/24。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。