@react-md/states

@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

npm install --save @react-md/states

It is also recommended to install the following packages:

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

Documentation

You should check out the full documentation for live examples and more customization information, but an example usage is shown below.

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.

import React from "react";
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.

import React from "react";
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.

import React, { FC, HTMLAttributes } from "react";
import { render } from "react-dom";
import {
  StatesConfig,
  userInteractionStates,
  InteractionStatesOptions,
} from "@react-md/states";

type ButtonProps = HTMLAttributes<HTMLButtonElement> &
  InteractionStatesOptions<HTMLButtonElement>;
const Button: FC<ButtonProps> = ({
  className: propClassName,
  disabled,
  disableRipple,
  disableProgrammaticRipple,
  disableSpacebarClick,
  disablePressedFallback,
  children,
  ...propHandlers
}) => {
  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>
  );
};

const App = () => (
  <>
    <Button>Button 1</Button>
    <Button disableRipple>Button 2</Button>
    <Button disableRipple disablePressedFallback>
      Button 3
    </Button>
  </>
);

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

Changelog

2.7.0 (2021-02-28)

Bug Fixes

• @react-md/alert: fixed alert color when dark theme elevation is enabled (99cc271), closes #1075
• @react-md/card: fixed card color when dark theme elevation is enabled (e5da5f5), closes #1075
• @react-md/dialog: fixed dialog color when dark theme elevation is enabled (e79993d), closes #1075
• @react-md/form: fixed listbox color when dark theme elevation is enabled (b68ac04), closes #1075
• @react-md/menu: fixed menu color when dark theme elevation is enabled (52c752d), closes #1075
• @react-md/sheet: fixed sheet color when dark theme elevation is enabled (0abe05e), closes #1075

Features

• @react-md/layout: added support for mini layouts (36b3cbc)
• @react-md/utils: added a low level RadioGroup widget for the radiogroup role (76d6d27)

Documentation

• updated Used By/Requires SassDoc to be collapsible (37a7536)
• @react-md/theme: added additional dark-theme-elevation SassDoc examples (172ee40)
• react-md.dev: added information about Noninteractable Chips demo (42e929b)
• react-md.dev: updated layout demos for mini layout support (1065688)
• tsdoc: fixed remaining tsdoc syntax warnings (946f4dd)
• tsdoc: fixed some tsdoc annotations and styling (0449b86)
• tsdoc: updated @since annotations (c62027e)

Other Internal Changes

• updated test coverage to not include conditional component PropTypes (24e5df1)
• @react-md/dev-utils: release script will now automatically create github release (83c2b65)
• @react-md/utils: added tryToSubmitRelatedForm util to help with additional a11y (0566e14)
• @react-md/utils: updated loop util to allow for a specific min value (51bcf92)