@gitlab/ui

中文文档
140.1.1发布于 2026/11/14MITESM + CJS近 30 天下载 40.8万

GitLab UI Components

原始使用文档
文档目录11 节
  1. Usage
  2. Quick start - development
  3. Testing
  4. Unit tests
  5. SCSS tests
  6. Visual regression tests
  7. End to end tests
  8. Design tokens
  9. Releases
  10. Contributing guide
  11. FAQs

GitLab UI

GitLab UI is a UI component library that implements Pajamas, our design system. GitLab UI is written in Vue.js and its objectives are to:

  • Create reusable UI components to accelerate frontend development.
  • Create UI consistency for all components within GitLab.

See https://design.gitlab.com/storybook for documentation.

Usage

  1. To use GitLab UI in your project, add it as a dependency:

    yarn add @gitlab/ui
    

    Note: Make sure to also install GitLab UI's peer dependencies. Refer to the package.json for the list of peer dependencies and their expected versions.

  2. In your main entrypoint before importing or using any component:

    import setConfigs from '@gitlab/ui/dist/config';
    
    setConfigs();
    

    This will set the global configs used by GitLab UI.

  3. Include the required stylesheets in your app. Refer to the CSS docs for installation options.

  4. Import the components as desired:

    import { GlButton } from '@gitlab/ui';
    

    Note: GitLab UI is compatible with tree-shaking, you may enable this in your project to reduce bundle sizes.

Quick start - development

Note: GitLab UI isn't designed to be built on Windows natively. Either WSL or GitPod can be used to set up a UNIX-like environment in which to build it.

Complete the project setup in the repository root README, then build and launch Storybook:

cd packages/gitlab-ui
yarn storybook

Go to http://localhost:9001/

Testing

Unit tests

Components’ unit tests live in the tests/components. The tests are organized following the same directory structure used to organize components.

  • yarn test:unit runs all unit tests.

  • yarn test:unit:watch runs all unit tests in watch mode.

  • yarn test:unit:debug runs all unit tests and allow to attach a debugger to the test runner process.

  • yarn jest [name_pattern] runs spec files that match the specified name pattern.

Examples

  • yarn jest datepicker will match all spec files with a name that contains the word datepicker.

  • yarn jest datepicker -t "when draw event is emitted" goes a step further and only runs the test with a description that matches the argument passed to the t flag.

SCSS tests

Even though we try to avoid writing complex SASS code to maintain CSS complexity low, we’ve implemented some functions that benefit from automated testing. SASS tests live in the tests/scss directory. GitLab UI uses sass-true to implement these tests, and jest run them.

yarn jest run_scss_tests runs all SCSS tests.

Visual regression tests

GitLab UI uses visual snapshot tests to prevent introducing regressions with CSS and layout changes on components. Read more on this in the visual testing documentation.

GitLab visual regression tests

GitLab UI components are a reference implementation of the Pajamas Design System components. These components should conform with the design system specs, and they should look correct in the pajamas website and the GitLab product. Please see Debugging GitLab UI issues with GitLab product CSS for information on how to debug issues with GitLab product CSS in GitLab UI.

End to end tests

Components’ end to end tests live in the cypress/e2e folder. See our end to end testing documentation for more details.

yarn run cypress open runs Cypress locally to run end to end tests.

Design tokens

GitLab UI uses design tokens to maintain a single source of truth that, through automation, can be formatted for different uses. Read more on this in the design tokens documentation.

Releases

See Updating GitLab UI Packages for information on how the @gitlab/ui package is kept up to date in various projects.

To publish new versions of GitLab UI, see publishing packages.

Contributing guide

Please review the design system contribution process for an overview of how to contribute to Pajamas.

For GitLab UI–specific details, refer to Contributing to GitLab UI for additional resources and guides.

FAQs

Any question? Have a look at our FAQ.md, you might find the answer there.

版本与发布记录

@gitlab/ui 共发布 2,029 个版本,首次发布于 2018/11/16;过去 12 个月发布了 151 个版本。

版本发布日期距今
140.1.1latest2026/11/141 天前
140.1.02026/11/132 天前
140.0.22026/11/114 天前
140.0.12026/11/105 天前
140.0.02026/11/096 天前
139.0.02026/11/0510 天前

关于 @gitlab/ui 的常见问题

@gitlab/ui 是什么?

GitLab UI Components

如何安装 @gitlab/ui?

在项目目录运行 npm install @gitlab/ui,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:vue(^2.7.16)、pikaday(^1.8.0)、dompurify(>=2.5.2 <3.0.0 || >=3.1.2)、emoji-regex(>=10.0.0)、tailwindcss(^3)、@gitlab/svgs(^1.116.0 || ^2.0.0 || ^3.0.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@gitlab/ui 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/gitlab__ui 是否存在。

@gitlab/ui 支持 ESM 还是 CommonJS?

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

@gitlab/ui 可以商用吗?

@gitlab/ui 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gitlab/ui 的下载量有多少?

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

@gitlab/ui 还在维护吗?

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