react-icon-layout

React hook for displaying icon-to-text relationships.

Features

• 3 common display modes: Icon and Text, Icon Only, or Text Only.
• Styles for positioning of icon to text while maintaining source order.
• Styles for positioning of <IconLayout> within a larger parent.

Installation

npm i -S react-icon-layout

or

yarn add react-icon-layout

Usage

Basic Example

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

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

const NextButton = props => (
  <button type="button" {...props}>
    <IconLayout
      icon={<ArrowRightIcon />}
      text="Next"
      direction="right"
      placement="right"
    />
  </button>
);

const IconLayoutPicker = () => {
  const [iconLayout, dispatch] = useIconLayout();
  return (
    <select
      value={iconLayout}
      onChange={event => dispatch({ type: event.target.value })}
    >
      {iconLayoutOptions.map(({ id, name }) => (
        <option key={id} value={id}>
          {name}
        </option>
      ))}
    </select>
  );
};

const App = () => (
  <IconLayoutProvider>
    <NextButton />
    <IconLayoutPicker />
  </IconLayoutProvider>
);

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

• View “Basic” demo on CodeSandbox

Advanced Examples

• View “Finder” demo on CodeSandbox
• View “example” folder on GitHub
• View “stories” folder on GitHub

API

Exports

import {
  IconLayout, // Context consumer and display component
  IconLayoutProvider, // Context provider component
  defaultIconLayout, // Default context state
  defaultIconLayoutPosition, // Default context consumer prop value
  iconLayoutOptions, // List of context ids and names
  iconLayoutPositions, // List of context consumer prop values
  iconLayouts, // List of context states
  useIconLayout, // Context consumer hook and updater
} from 'react-icon-layout';
import 'react-icon-layout/styles.css'; // Styles for <IconLayout>

<IconLayoutProvider>

import { IconLayoutProvider } from 'react-icon-layout';

const App = () => (
  <IconLayoutProvider value="textOnly">
    <div>exampleChild</div>
  </IconLayoutProvider>
);

value

value?: 'iconAndText' | 'iconOnly' | 'textOnly' | null;

Initial context state. Default: 'iconAndText'.

children

children: React.ReactNode;

Consumer component(s). Required.

<IconLayout>

import { IconLayout } from 'react-icon-layout';
import 'react-icon-layout/styles.css';

const ExampleIconLayout = props => (
  <IconLayout
    {...props}
    className="exampleIconLayout"
    direction="left"
    placement="left"
    icon="exampleIcon"
    text="exampleText"
  />
);

className

className?: string;

CSS class name(s). Default: null

direction

direction?: 'top-left' | 'top' | 'top-right' | 'left' | 'center' | 'right' | 'bottom-left' | 'bottom' | 'bottom-right' | null;

Styles the positioning of icon to text while maintaining source order. Default: 'center'.

placement

placement?: 'top-left' | 'top' | 'top-right' | 'left' | 'center' | 'right' | 'bottom-left' | 'bottom' | 'bottom-right' | null;

Styles the positioning of the component within a larger parent. Default: null.

icon

icon: React.ReactNode; Required.

Slot for the icon, similar to a children prop.

text

text: React.ReactNode; Required.

Slot for the text, similar to a children prop.

useIconLayout()

import { useIconLayout } from 'react-icon-layout';

const TextOnlyButton = props => {
  const [state, dispatch] = useIconLayout();
  return (
    <button
      {...props}
      type="button"
      onClick={() => dispatch({ type: 'textOnly' })}
    >
      Text Only
    </button>
  );
};

const useIconLayout: () => readonly ['iconAndText' | 'iconOnly' | 'textOnly', React.Dispatch<ActionType>]

state

Initial context state. Default: 'iconAndText'.

dispatch()

{ type: 'iconAndText' } | { type: 'iconOnly' } | { type: 'textOnly' } | { type: 'reset' }

Method to update context state.

License

MIT