npm package: @lokalise/louis
Description: Welcome to **Louis**. This project, built by [Lokalise](https://www.lokalise.com), is a ReactJS implementation of the Louis Design System. It contains the core components to start building your React application with Lokalise's look and feel.
Author: Lokalise
Latest version: 28.6.0

# Louis

Welcome to **Louis**. This project, built by [Lokalise](https://www.lokalise.com), is a ReactJS implementation of the Louis Design System. It contains the core components to start building your React application with Lokalise's look and feel.

Check Louis [production storybook](https://lokalise.github.io/louis/) and [figma ui library](https://www.figma.com/file/zfCOLmZam4nrttG6IVzQyz/UI-Library?node-id=392%3A3448).

---

![PRs Welcome](https://img.shields.io/badge/PRs-Welcome-red.svg)
![ReactJS18](https://img.shields.io/badge/ReactJS-18-blue.svg)
![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)
![semantic-release: angular](https://img.shields.io/badge/semantic--release-angular-e10079?logo=semantic-release)
![npm](https://img.shields.io/npm/v/@lokalise/louis)

## Prerequisites

Make sure your application bundler (e.g. [Webpack](https://webpack.js.org/)) does have a loader (e.g. [style-loader](https://webpack.js.org/loaders/style-loader/)) for bundling CSS files.

## Installation

To use Louis in your project, run the following command in your terminal:

```shell
npm i @lokalise/louis
```

After installing Louis, you need to set up a `ThemeProvider` at the root of your application:

```tsx
import { ThemeProvider, themes } from '@lokalise/louis';

const App = () => (
	<ThemeProvider theme={themes.light}>
		<TheRestOfYourApplication />
	</ThemeProvider>
);
```

From here on out, you can import and use Louis components anywhere:

```tsx
import { Button } from '@lokalise/louis';
import { useState } from 'react';

export const MyCounter = () => {
	const [count, setCount] = useState(0);
	return (
		<>
			<p>{`You've clicked the button ${count} times!`}</p>
			<Button variant="primary" onClick={() => setCount(count + 1)}>
				Click to increase the counter
			</Button>
		</>
	);
};
```

## Styling and CSS

### Default Import

Import Louis styles in your application:

```tsx
import '@lokalise/louis/style.css';
```

### Tailwind CSS v4 Compatibility

If you're using Tailwind CSS v4 (which uses CSS layers by default), import the layered version in your main CSS file to avoid specificity conflicts:

```css
@import '@lokalise/louis/style-layered.css';

/* Control layer precedence - Tailwind utilities can override Louis component styles */
@layer louis, tailwind;
```

This ensures Tailwind utility classes can override Louis component styles when needed.

**Note:** Import either `style.css` or `style-layered.css`, not both. Choose `style-layered.css` when using Tailwind CSS v4.

#### Known Limitations

When using `style-layered.css`, be aware that unlayered styles from third-party libraries will always override layered Louis styles, regardless of layer order. This is expected CSS cascade layer behavior where unlayered styles have higher precedence than any layered styles.

Specifically, this affects Louis components that depend on third-party libraries with runtime-generated styles:

- **Select/Multiselect components**: These use react-select, which generates unlayered emotion styles at runtime. When using `style-layered.css`, these components will appear with react-select's unstyled minimal default appearance (basic dropdown controls with minimal styling) instead of Louis's custom theme. To preserve Louis's styling for these components, use the default `style.css` import instead.

## Reporting issues 

You can report issues on our [JIRA Project](https://lokalise.atlassian.net/jira/software/c/projects/FF/boards/454), reach us on [Slack](https://lokalise.slack.com/archives/C038HSS6YM8) or submit a [Support Request](https://lokalise.atlassian.net/servicedesk/customer/portal/24/group/59/create/218).

## How to contribute

Check our guidelines [here](https://github.com/lokalise/louis/blob/main/CONTRIBUTING.md)

## Code of Conduct

Follow up on our [code of conduct](https://github.com/lokalise/louis/blob/main/CODE_OF_CONDUCT.md)

## Thanks

Louis relies heavily on some of the approaches provided by [Chakra-UI](https://github.com/chakra-ui/chakra-ui) and [Reach UI](https://github.com/reach/reach-ui).

## License

This project is [APACHE, VERSION 2.0](https://github.com/lokalise/louis/blob/main/LICENSE.md) licensed.