# @react-md/states

> A package for adding the different focus, hover, selected, active, etc states to elements

Latest version **5.1.6** (published 2023-12-11) · MIT license · 0 weekly downloads

## Install

```sh
npm install @react-md/states
pnpm add @react-md/states
yarn add @react-md/states
bun add @react-md/states
```

## Health

**Score 40/100 (D)** — status: abandoned.

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

Warnings: low downloads.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 5.1.6 |
| Published | 2023-12-11 |
| First published | 2019-03-17 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 4 |
| Unpacked size | 269.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2324 |
| Author | Mikkel Laursen |
| Maintainers | mlaursen |
| Keywords | accessibility, a11y, react-md, keyboard, focus, selection |

## Links

- npm: https://www.npmjs.com/package/@react-md/states
- Repository: https://github.com/mlaursen/react-md
- Homepage: https://react-md.dev/packages/states/demos
- Issues: https://github.com/mlaursen/react-md/issues
- npm.io page: https://npm.io/package/@react-md/states

## Dependencies (4)

- [classnames](https://npm.io/package/classnames.md) ^2.3.1
- [@react-md/theme](https://npm.io/package/@react-md/theme.md) ^5.1.6
- [@react-md/utils](https://npm.io/package/@react-md/utils.md) ^5.1.6
- [@react-md/transition](https://npm.io/package/@react-md/transition.md) ^5.1.6

## Alternatives

- [@mdxeditor/editor](https://npm.io/package/@mdxeditor/editor.md) — 962.4K weekly downloads
- [mmdb-lib](https://npm.io/package/mmdb-lib.md) — 680.9K weekly downloads
- [playcanvas](https://npm.io/package/playcanvas.md) — 36.2K weekly downloads
- [@glw907/cairn-cms](https://npm.io/package/@glw907/cairn-cms.md) — 967 weekly downloads
- [markdown-to-confluence](https://npm.io/package/markdown-to-confluence.md) — 103 weekly downloads

## Recent versions

- 5.1.6 (latest) — 2023-12-11
- 3.0.1-alpha.2 (next) — 2021-08-15
- 5.1.3 — 2022-05-07
- 5.1.2 — 2022-04-02
- 5.1.0 — 2022-03-18
- 5.0.0 — 2022-01-31
- 4.0.3 — 2022-01-01
- 4.0.1 — 2021-11-27
- 4.0.0 — 2021-11-24
- 3.1.0 — 2021-09-10
- 3.0.1 — 2021-08-15
- 3.0.1-alpha.1 — 2021-08-15
- 3.0.1-alpha.0 — 2021-08-15
- 3.0.0 — 2021-08-13
- 3.0.0-alpha.0 — 2021-08-11
- … 47 more at https://npm.io/package/@react-md/states/versions

## README

# @react-md/states

This package is used to create different interaction states for when a user is
touching, hovering, pressing, or keyboard focusing an element on the page. There
are also some mixins and styles that allow you to apply styles only while the
user is in "touch", "mouse", or "keyboard" mode so you can finally get that
amazing keyboard focus only effect going on.

## Installation

```sh
npm install --save @react-md/states
```

It is also recommended to install the following packages:

```sh
npm install --save @react-md/theme \
  @react-md/typography \
  @react-md/utils
```

<!-- DOCS_REMOVE -->

## Documentation

You should check out the
[full documentation](https://react-md.dev/packages/states/demos) for live
examples and more customization information, but an example usage is shown
below.

<!-- DOCS_REMOVE_END -->

## Usage

This package has two main exports: `StatesConfig` and `useInteractionStates`.

### StatesConfig

This component is used to apply global configuration for how your user
interactions should work as well as determining the user input mode for your
app. There should only be _one_ `StatesConfig` component defined in your app at
a time and it should probably be somewhere near the root of your React render
tree since this component will modify the base `document.body` element with a
different `className` to help determine the current interaction mode.

```tsx
import { render } from "react-dom";
import { StatesConfig } from "@react-md/states";

import App from "./App";

const Root = () => (
  <StatesConfig>
    <App />
  </StatesConfig>
);

render(<Root />, document.getElementById("root"));
```

Since some people do not actually like the ripple effect from material design,
you can also configure the `StatesConfig` to remove the ripples altogether and
fallback to the default "pressed" states which will just change background color
temporarily instead.

```tsx
import { render } from "react-dom";
import { StatesConfig } from "@react-md/states";

import App from "./App";

const Root = () => (
  <StatesConfig disableRipple>
    <App />
  </StatesConfig>
);

render(<Root />, document.getElementById("root"));
```

### useInteractionStates

This is a hook that will allow you to connect to the current `StatesConfig` and
apply the different interaction states for an element. This hook will always
return an object containing:

- `ripples` - `ReactNode` of the ripples when enabled or `null` when ripples are
  disabled
- `className` - A merged `className` if using the pressed fallback state when
  ripples are disabled
- `handlers` - An object containing all the event handlers that must be applied
  to the DOM element so all the interaction states can happen.

```tsx
import type { HTMLAttributes, ReactElement } from "react";
import { render } from "react-dom";
import {
  StatesConfig,
  userInteractionStates,
  InteractionStatesOptions,
} from "@react-md/states";

type ButtonProps = HTMLAttributes<HTMLButtonElement> &
  InteractionStatesOptions<HTMLButtonElement>;
function Button({
  className: propClassName,
  disabled,
  disableRipple,
  disableProgrammaticRipple,
  disableSpacebarClick,
  disablePressedFallback,
  children,
  ...propHandlers
}: ButtonProps): ReactElement {
  const { ripples, handlers, className } = useInteractionStates({
    handlers: propHandlers,
    className: propClassName,
    disabled: disabled,
    disableRipple,
    disableProgrammaticRipple,
    disableSpacebarClick,
    disablePressedFallback,
  });

  return (
    <button type="button" className={className} {...handlers}>
      {children}
      {ripples}
    </button>
  );
}

function App(): ReactElement {
  return (
    <>
      <Button>Button 1</Button>
      <Button disableRipple>Button 2</Button>
      <Button disableRipple disablePressedFallback>
        Button 3
      </Button>
    </>
  );
}

render(<App />, document.getElementById("root"));
```

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