# <img src="https://unpkg.com/@moneyforward/mfui-components/logo_with_isolation.svg" alt="Money Forward UI"/>

# MFUI Components

React components for basic UI parts and layouts.

- [Changelog](https://github.com/moneyforward/mfui/blob/main/packages/components/CHANGELOG.md)

## Library Requirements

MFUI requires certain libraries. Please check their versions.
You can also check the recommended environment by referring to the libraries used in the projects under the `examples/` directory.

### Requirements

MFUI Components requires the following libraries with minimum versions:

- React & React DOM: ≥18
- TypeScript: ≥5.1.0

### Notices

The following libraries are not mandatory, but if you are using them, MFUI requires at least the versions listed below:

- Tailwind CSS ≥3.4.2

For detailed setup instructions with Tailwind CSS (v3 and v4), see the [Tailwind Integration Guide](https://github.com/moneyforward/mfui/blob/main/docs/usage/tailwind-integration.md).

## Installation

### 1. Install the Package

Run the following command to install the package:

```zsh
npm install @moneyforward/mfui-components
```

### 2. Install the Peer Dependencies

This package requires `react` and `react-dom` with version 17 or above as peer dependencies.

```zsh
npm install react react-dom
```

### 3. (Only Vite with SSR user) Add libraries to the noExternal dependencies

<!--
TODO: Remove this after we support providing ES Modules.
This is a workaround to prevent error caused by untranspiled the package.
In Vite with SSR mode, the libraries inside a node_modules won't be a target of bundle.
However, since mfui libraries doesn't provide as ES Modules, it need to be transpiled.
So after we support ES Modules, we can remove this step
https://vite.dev/guide/ssr#ssr-externals
-->

If you're using Vite with Server Side Rendering feature, this step is required.
Please add both `@moneyforward/mfui-components` and `@moneyforward/mfui-icons-react` to `ssr.noExternal` in your `vite.config.ts`.

```ts
export default defineConfig({
  // Other configurations
  ssr: {
    noExternal: ['@moneyforward/mfui-components', '@moneyforward/mfui-icons-react'],
  },
});
```

## Usage

### Import Styles to Your Global Stylesheet

Add the following line into your global stylesheet (e.g. globals.css for Next.js application):

```css
@import url('@moneyforward/mfui-components/styles.css');
```

### Use Components

This is the basic usage of Button. See the official documentation for all available components and how to use their properties.

```tsx
import { Button } from '@moneyforward/mfui-components';

export function Foo() {
  return <Button priority="primary">Label</Button>;
}
```

### Use Icons

Use icons by importing from `@moneyforward/mfui-icons-react`. See the official documentation for all available icons.

```tsx
import { Add } from '@moneyforward/mfui-icons-react';
import { IconButton } from '@moneyforward/mfui-components';

export function Bar() {
  return (
    <IconButton>
      <Add />
    </IconButton>
  );
}
```

### Reduce Bundle Size

If bundle size is a concern, import components from their specific paths so that
tree shaking works with Next.js and Vite.

```tsx
import { IconButton } from '@moneyforward/mfui-components/IconButton';
```

By importing components this way, unused code can be omitted from the final
bundle.

## About Experimental Features

Some features may be released in an "Experimental" state. These features are primarily in one of the following situations:

- Features whose specifications defined in the design standards have not received sufficient feedback from products
- Features that have well-defined design standards but need validation for React component usability

This experimental status allows us to gather practical feedback while ensuring the features meet our minimum quality standards.

### Definition of Experimental

- Breaking changes may occur
- Some features may be missing or incomplete
- Requirements may not be fully defined
- A minimum quality standard of 60% is ensured
- Expected to become stable in the next major release

### Identifying Experimental Features

Experimental features can be identified through:

- An "Experimental" tag in Storybook
- "Experimental" annotations in JSDoc

---

All company names, product and service names, and logos are trademarks or registered trademarks of their respective owners.