JTL-Platform UI React

A modern, accessible UI component library for JTL applications built with React and TailwindCSS.

📦 Installation

Install the package using npm or yarn:

# Using npm
npm install @jtl-software/platform-ui-react

# Using yarn
yarn add @jtl-software/platform-ui-react

🔨 Setup

1. TailwindCSS Configuration

This library requires TailwindCSS 4. If you haven't set up TailwindCSS in your project yet, follow the official Tailwind CSS installation guide.

2. Import Styles

In your main CSS file (e.g., globals.css or index.css), import the library styles:

@import '@jtl-software/platform-ui-react/dist/main.css';
@import 'tailwindcss';
@source 'node_modules/@jtl-software/platform-ui-react/dist';

🚀 Usage

Basic Component Usage

import { Button, Text, Card } from '@jtl-software/platform-ui-react';

🧩 Component Categories

This library includes the following component categories:

Layout Components

• Box, Grid, Stack, Layout, LayoutSection, Card

Form Components

• Button, Checkbox, Input, InputOTP, Radio, Select, Textarea, Switch, Toggle, ToggleGroup, FormGroup, Form

Data Display

• Text, Badge, Avatar, Table, DataTable, Progress

Navigation

• Link, Breadcrumb, Tab, Dropdown

Feedback

• Alert, Dialog, AlertDialog, Tooltip, Skeleton

Utility

• Icon, Separator, ScrollArea, Collapsible, Popover, Sheet

⚠️ Usage Guidelines

• Avoid invalid HTML nesting (e.g., <div> inside <p>, <button> containing <a>).
• Do not wrap library components with arbitrary elements unless semantically correct.
• Fix any console warnings like Warning: validateDOMNesting(...).

📚 Storybook

The best way to explore all available components and their usage is through Storybook

Running Storybook Locally

After cloning and installing dependencies:

# Install dependencies
yarn install

# Start Storybook
yarn storybook

Storybook will be available at: http://localhost:50170

Using Storybook for Documentation

Our Storybook includes:

• Component demonstrations with various prop combinations
• Interactive controls to experiment with component properties
• Documentation on component APIs, props, and examples
• Accessibility information
• Source code examples

⚡️ Development

If you're contributing to this library:

• Ensure you are using the Node.js version specified in the .nvmrc file. You can switch to the correct version by running nvm use in the project root. If the .nvmrc version needs to be updated (e.g., to match the latest Node.js LTS), please coordinate with the team before making changes to ensure consistency across the project and CI/CD pipelines.
• Run yarn install on repository root to install husky with dependencies
• Start Storybook with yarn storybook
• Build the library with yarn build
• Run tests with yarn test

🔌 Ports

To prevent conflicts with other services during development, we have a reserved port range for this project: 50170-50179. Please use a port within this range when adding a new service.

| Port | Protocol | Service | | ----- | -------- | --------- | | 50170 | HTTP | Storybook |

📦 Dependencies

This project uses React 19 for both development and as a peer dependency.

"peerDependencies": {
  "react": "^19.0.0",
  "react-dom": "^19.0.0",
}

Projects using this library should use React 19 for optimal compatibility.