Gazelle components / hooks library

🧩 Components

Gazelle Component UI is a library of reusable UI components for Next.js & React applications. This library aims to provide a set of well-designed and accessible components to speed up the development process and ensure consistency across the Gazelle application.

📁 Refer to src/components to see the list of available components or check them out directly on the Storybook page.

🪝 Custom Hooks

Additionally, our component library provides a set of generic hooks that can seamlessly integrate into your applications. These hooks offer versatile functionality, enhancing flexibility and extensibility.

📁 Refer to src/hooks to see the list of available hooks.

⚠️ Next.js Requirement

This library is intended to be used only with Next.js applications.

Supported Versions

• Next.js 15.x: Only 15.5.7
• Next.js 16.x: 16.1.1 and above

⚠️ Important: Do not use this library with other Next.js versions.
Versions outside these ranges may contain critical security vulnerabilities.

⚠️ *Note: This library is actively maintained and regularly updated with new features and improvements. So do not forget to upgrade the library.*

📦 Installation

You can install the gazelle-component-ui package via npm:

pnpm add gazelle-component-ui

🧑‍💻 Usage

To use the components from gazelle-component-ui in your React application, import the desired component and use it like any other React component.

A simple button component with various customization options.

Required Props

| Prop | Type | Description | | --------- | ------ | -------------------------------- | | id | string | Id for automatic test | | children | node | Content of the button. | | type | union | button | | title | string | Title attribute for the button. | | ariaLabel | string | ARIA label for accessibility. | | variant | union | primary, secondary or validation |

Here is an example demonstrating how to use a Button component from the library:

import React from "react";
import { Button } from "gazelle-component-ui";

const App = () => {
  return (
    <div>
      <h3>Welcome to Gazelle Component UI</h3>
      <Button id={id} type={type} title={title} aria-label={ariaLabel} onClick={() => alert("Button clicked!")} variant={primary}>
        Click Me
      </Button>
    </div>
  );
};

export default App;

✅ Unit testing component with vitest

🔍 1. Run Tests:

Use the basic test command to execute all unit tests

pnpm test

📊 2. Generate Coverage Reports:

To generate a code coverage report, use:

pnpm run test:coverage

This will output the test coverage details, indicating how much of your code is tested.

🌐 3. Interactive Coverage Report:

For an interactive user interface to explore test coverage, run:

pnpm run vitest:coverage

This starts Vitest’s UI with test and coverage details accessible in the browser.

📖 Storybook Documentation

We use Storybook to document and showcase the components provided by Gazelle Component UI. Storybook provides an interactive UI environment where you can browse, view, and test components in isolation.

🚀 Running Storybook

To view the documentation and interact with the components in Storybook:

1. Clone the repository:

git clone https://gitlab.inria.fr/gazelle/private/new-gazelle/user-interface/gazelle-component-lib.git

2. Install dependencies:

pnpm install

3. Start Storybook:

pnpm run storybook

4. Open Storybook in your browser:

Navigate to http://localhost:6006 to view the Storybook interface.

Using Storybook

In the Storybook interface, you can:

• Browse Components: Navigate through the list of available components.

• View Documentation: Read detailed documentation for each component, including props and usage examples.

• Interact with Components: Test and interact with components in real-time.

🚢 Test & publish the library

In order to use this library in all other Next-JS projects, we need to publish the components on a registry.

For registry, we are using https://www.npmjs.com.

Prerequisites

• Check that you are authenticated to the registry (npm whoami), if not, use the command npm adduser.

• Check the version in your package.json. You can't push a library on an existing version.

Test your component before publishing to npm

Two methods are available to test your new component in your current application, follow these steps:

Method 1: Using NPM Link

1. Build your component

Ensure your component is built and ready for use by running:

pnpm build

2. Link the component locally

Link your component globally in your development environment:

pnpm link

3. Link the component in your application

In the application or repository where you want to test the component, run:

pnpm link gazelle-component-ui

Method 2: Using NPM Pack (Recommended)

Below command will do the following as one

pnpm package

1. Build your component

Ensure your component is built and ready for use by running:

pnpm build

2. Create a tarball package

Create a local tarball package of your component library:

pnpm pack

This command will generate a file named gazelle-component-ui-{VERSION}.tgz in your project root directory, where {VERSION} matches the version in your package.json.

3. Install the package in your application

In the application where you want to test the component, install the local package using the absolute path to the tarball:

# If using npm
npm install /absolute/path/to/gazelle-component-ui-{VERSION}.tgz

# If using pnpm
pnpm install /absolute/path/to/gazelle-component-ui-{VERSION}.tgz

Replace /absolute/path/to/ with the actual path to your component library directory.

Note: This approach creates a more realistic testing environment as it exactly replicates how the package would behave when installed from the npm registry.

Publishing Your Component

Once you’ve tested your component and are ready to publish a new version to the npm registry, follow these steps:

1. Update the version

Use the following command to update your package version:

pnpm version patch

2. Authenticate to npm registry

If you are not already authenticated, log in to the npm registry:

npm set "//registry.npmjs.org/:_authToken=<AUTH_TOKEN>"

You need to generate an authentication token from your npm account settings.

Be careful to bypass two-factor authentication if enabled on your account.

Tokens have limited lifespan of 90 days.

3. Publish to the npm registry

Publish the new version of your package:

pnpm publish

✅ Don't forget to push your changes to the library repository to ensure the latest updates are tracked and shared.

4. Verify the publication

Once published, verify the package on the npm registry:

• Visit the package page on npm.
• Install the package in another project using:

pnpm add gazelle-component-ui

Once the library is pushed, you can go to your Next-JS application to change the library version in the package.json. Execute the pnpm install command. You can now use the components you developed.

📝 License

    Copyright 2022-2026 IHE International

    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Versioning

This project follows Semantic Versioning.
See VERSIONING.md for details.

Changelog

See CHANGELOG.md for details.