# react-icon-layout

> Everything you need to manage icon-to-text layouts.

Latest version **3.0.0** (published 2022-04-17) · MIT license · 0 weekly downloads

## Install

```sh
npm install react-icon-layout
pnpm add react-icon-layout
yarn add react-icon-layout
bun add react-icon-layout
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.0.0 |
| Published | 2022-04-17 |
| First published | 2019-12-05 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=14 <17 |
| Dependencies | 0 |
| Unpacked size | 57 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Michael Schwobe |
| Maintainers | michaelschwobe |
| Keywords | react, icon, layout, settings, hooks |

## Links

- npm: https://www.npmjs.com/package/react-icon-layout
- Repository: https://github.com/michaelschwobe/react-icon-layout
- Homepage: https://github.com/michaelschwobe/react-icon-layout#readme
- Issues: https://github.com/michaelschwobe/react-icon-layout/issues
- npm.io page: https://npm.io/package/react-icon-layout

## Alternatives

- [@fortawesome/react-fontawesome](https://npm.io/package/@fortawesome/react-fontawesome.md) — 2.2M weekly downloads
- [roboto-fontface](https://npm.io/package/roboto-fontface.md) — 196.0K weekly downloads
- [@react-native-vector-icons/common](https://npm.io/package/@react-native-vector-icons/common.md) — 150.4K weekly downloads
- [@procore/core-icons](https://npm.io/package/@procore/core-icons.md) — 4.6K weekly downloads
- [@react-md/material-icons](https://npm.io/package/@react-md/material-icons.md) — 1.6K weekly downloads

## Recent versions

- 3.0.0 (latest) — 2022-04-17
- 2.0.2 — 2022-04-08
- 2.0.1 — 2022-04-08
- 2.0.0 — 2022-04-07
- 1.1.0 — 2021-02-26
- 1.0.0 — 2020-03-16
- 0.3.0 — 2019-12-20
- 0.2.1 — 2019-12-05
- 0.2.0 — 2019-12-05

## README

# react-icon-layout

Everything you need to manage icon-to-text layouts.

[![NPM version](https://img.shields.io/npm/v/react-icon-layout.svg)](https://www.npmjs.com/package/react-icon-layout)
[![License](https://img.shields.io/npm/l/react-icon-layout)](https://github.com/michaelschwobe/react-icon-layout/blob/master/LICENSE)
[![NPM status](https://img.shields.io/github/workflow/status/michaelschwobe/react-icon-layout/CI)](https://www.npmjs.com/package/react-icon-layout)
[![Publish](https://github.com/michaelschwobe/react-icon-layout/actions/workflows/publish.yml/badge.svg)](https://github.com/michaelschwobe/react-icon-layout/actions/workflows/publish.yml)
[![CI](https://github.com/michaelschwobe/react-icon-layout/actions/workflows/ci.yml/badge.svg)](https://github.com/michaelschwobe/react-icon-layout/actions/workflows/ci.yml)
[![CodeQL](https://github.com/michaelschwobe/react-icon-layout/actions/workflows/codeql.yml/badge.svg)](https://github.com/michaelschwobe/react-icon-layout/actions/workflows/codeql.yml)
[![codecov](https://codecov.io/gh/michaelschwobe/react-icon-layout/branch/master/graph/badge.svg?token=NN3EY45TXL&)](https://codecov.io/gh/michaelschwobe/react-icon-layout)

Jump to: [Overview](#overview) | [Installation](#installation) | [Usage](#usage) | [Features](#features) | [API](#api) | [License](#license)

## Overview

As a developer, you’d like to:

- 👯 Create icon-to-text pairs (or other content types) multiple times, and possibly nest them.
- ⚡️ Dynamically or statically control how some or all icon-to-text pairs display.
- ✍️ Use custom or default styles and variables.

So that you can:

- 🤝 Ensure layout relationships are consistent and manageable.
- ✨ Render whatever, wherever — form fields, navigation, pagination, etc.
- 🛠 Allow some or all users to control their own icon-to-text display settings.

For example, you’ve likely seen this use case before within the macOS Finder:

![macOS Finder with it’s header right-click menu visible](./media/Finder.png)

## Installation

```sh
npm i -S react-icon-layout
```

or

```sh
yarn add react-icon-layout
```

## Usage

- ⬆️ View the “Finder” example (shown above) on [CodeSandbox](https://codesandbox.io/s/react-icon-layout-finder-example-dzedn)
- 📚 View the Storybook example on [GitHub](./stories/react-icon-layout.stories.tsx) or clone locally then run the `dev` script.
- ⬇️ View the “Basic” example (shown below) on [CodeSandbox](https://codesandbox.io/s/react-icon-layout-basic-example-urw6e)

```js
import * as React from 'react';
import * as ReactDOM from 'react-dom';
import {
  IconLayout,
  IconLayoutProvider,
  iconLayoutOptions,
  useIconLayoutDispatch,
  useIconLayoutState,
} from 'react-icon-layout';
import 'react-icon-layout/styles.css';

import { ReactComponent as ArrowRightIcon } from './arrow-right.svg';

function NextButton() {
  const iconLayoutState = useIconLayoutState();
  return (
    <button type="button">
      <IconLayout
        icon={<ArrowRightIcon />}
        text="Next"
        placeIcon="right"
        placeSelf="right"
        variant={iconLayoutState}
      />
    </button>
  );
}

function IconLayoutSelector() {
  const iconLayoutState = useIconLayoutState();
  const iconLayoutDispatch = useIconLayoutDispatch();
  return (
    <label htmlFor="IconLayoutSelector">
      Select icon layout:{' '}
      <select
        name="IconLayoutSelector"
        id="IconLayoutSelector"
        value={iconLayoutState}
        onChange={(event) => iconLayoutDispatch({ type: event.target.value })}
      >
        {iconLayoutOptions.map(({ id, name }) => (
          <option key={id} value={id}>
            {name}
          </option>
        ))}
      </select>
    </label>
  );
}

function App() {
  return (
    <IconLayoutProvider>
      <NextButton />
      <IconLayoutSelector />
    </IconLayoutProvider>
  );
}

const rootElement = document.getElementById('root');
ReactDOM.render(<App />, rootElement);
```

## Features

```ts
import {
  /** Default `placeIcon` prop value */
  defaultPlaceIcon,
  /** Default `placeSelf` prop value */
  defaultPlaceSelf,
  /** Default `variant` prop value / context state */
  defaultVariant,
  /** List of `placeIcon` and `placeSelf` prop values */
  iconLayoutPlacements,
  /** List of `variant` prop values / context states */
  iconLayoutVariants,
  /** List for iterating button/input/option/etc elements */
  iconLayoutOptions,
  /** Display component */
  IconLayout,
  /** Context component for `state` */
  IconLayoutStateContext,
  /** Context component for `dispatch` */
  IconLayoutDispatchContext,
  /** Context provider component */
  IconLayoutProvider,
  /** Hook for accessing context `state` */
  useIconLayoutState,
  /** Hook for accessing context `dispatch` */
  useIconLayoutDispatch,
} from 'react-icon-layout';

/* Types for when using TypeScript */
import type {
  IconLayoutAction,
  IconLayoutDispatch,
  IconLayoutOptions,
  IconLayoutPlacement,
  IconLayoutProps,
  IconLayoutProviderProps,
  IconLayoutState,
} from 'react-icon-layout';

/* Styles for <IconLayout> */
import 'react-icon-layout/styles.css';
```

## API

### `<IconLayout>`

Display component, does **NOT** consume context.

```ts
/** Sets the `class` attribute. **Default:** `undefined` */
className?: string | undefined;
/** Styles the “icon” placement within the display component. **Default:** `"left"` */
placeIcon?: IconLayoutPlacement | undefined;
/** Styles the component placement within a larger parent. **Default:** `undefined` */
placeSelf?: IconLayoutPlacement | undefined;
/** Styles the content visibility. **Default:** `"iconAndText"` */
variant?: IconLayoutState | undefined;
/** Sets the “icon” content, similar to a `children` prop. **Required.** */
icon: React.ReactNode;
/** Sets the “text” content, similar to a `children` prop. **Required.** */
text: React.ReactNode;
```

### `<IconLayoutProvider>`

Provider component.

```ts
/** Sets the content. **Required.** */
children: React.ReactNode;
/** Sets the initial state. **Default:** `iconAndText` */
value?: IconLayoutState | undefined;
```

### `useIconLayoutState()`

Hook for accessing `state`, requires `<IconLayoutProvider>`.

### `useIconLayoutDispatch()`

Hook for accessing `dispatch`, requires `<IconLayoutProvider>`.

## License

[MIT](./LICENSE)

---
_Source: https://npm.io/package/react-icon-layout · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._