Styled-is Flag Utility for styled-components

Common errors

• TypeError: (0 , styled_is__WEBPACK_IMPORTED_MODULE_0__.is) is not a function

  cause The default export `is` was imported as a named export in a CommonJS or bundled environment (e.g., `import { is } from 'styled-is';`).
  fix Correct the import statement to use the default import syntax: `import is from 'styled-is';`

• Warning: Prop `[your-prop-name]` did not match. Server: `[value1]`. Client: `[value2]`.

  cause A mismatch in prop values or dynamic styling evaluation between server-side rendering (SSR) and client-side hydration, often due to non-deterministic logic or environment differences when `styled-is` functions are used with dynamic props.
  fix Ensure that any prop values affecting `styled-is` logic are consistent between server and client. For dynamic values that differ, consider using a `useState` hook with `useEffect` for client-side only effects, or use `suppressHydrationWarning` on the element if the mismatch is benign.

• ReferenceError: styled is not defined

  cause The `styled` object from `styled-components` was not imported or correctly configured before attempting to use it to create a styled component.
  fix Ensure `import styled from 'styled-components';` is present at the top of your file. If using `styled-components` v6+, ensure you are using named imports: `import { styled } from 'styled-components';`.

Warnings

• gotcha Ensure strict compatibility with your `styled-components` version. `styled-is` relies on `styled-components`' underlying API. Mismatches, especially between major `styled-components` versions (e.g., v4/v5 vs. v6+ which introduced breaking changes in module exports and prop handling), can lead to runtime errors or unexpected styling behavior. Always check the peer dependency range.
  Fix: Refer to the `styled-is` `package.json` for precise `styled-components` peer dependency versions. Upgrade or downgrade `styled-components` accordingly using `npm install styled-components@X.Y.Z` or `yarn add styled-components@X.Y.Z`.
• gotcha When using `is('propName')`, `styled-is` checks for the *truthiness* of the `propName`. If you intend to match a specific boolean value (`true` or `false`) or a non-truthy value other than `false`/`null`/`undefined`/`0`/`''`, you might need to pass a function or use `match` for explicit value checking.
  Fix: For explicit boolean `false` checks, use `isNot('propName')`. For specific values, use `match('propName', 'value')`. For complex logic, pass a function: `${is((props) => props.propName === true)`.
• gotcha In `styled-components` v6 and above, props not starting with `$` (transient props) that are passed to a styled component might be forwarded to the underlying DOM element, causing React warnings about unknown HTML attributes. While `styled-is` simplifies conditional logic, it doesn't automatically convert prop names to transient ones.
  Fix: Prefix props intended only for styling with a dollar sign (e.g., `$primary` instead of `primary`) when defining your styled components. Alternatively, configure `shouldForwardProp` via `StyleSheetManager` or `styled.div.withConfig()` to filter props.
• gotcha Defining `styled-components` within a React render function can lead to performance issues and unexpected behavior (like losing DOM state) because React remounts the component on every render. This principle also applies to the usage of `styled-is` helpers within such dynamically created styled components.
  Fix: Always define your styled components outside of the render method of your React components, typically at the top level of the file or in a separate styles file. This ensures they are created once and reused.

Install

• npm install styled-is npm
• yarn add styled-is yarn
• pnpm add styled-is pnpm

Imports

• is
  wrong:

  import { is } from 'styled-is';

  correct:

  import is from 'styled-is';

  The primary function for checking if one or more boolean props are truthy. It is typically imported as the default export.
• isNot
  wrong:

  import isNot from 'styled-is';

  correct:

  import { isNot } from 'styled-is';

  A named export used for checking when specified props are all falsey.
• match
  wrong:

  import match from 'styled-is';

  correct:

  import { match } from 'styled-is';

  A named export for matching a prop's value against a specific string or a function's return value.
• isOr
  wrong:

  import isOr from 'styled-is';

  correct:

  import { isOr } from 'styled-is';

  A named export for checking if *any* of the specified props are truthy.

Quickstart

This quickstart demonstrates how to use `styled-is` functions like `is`, `isNot`, `isOr`, and `match` to create conditionally styled `ThemedButton` components in a React application. It showcases various prop-based styling scenarios including simple booleans, combined booleans, value matching, and a dynamic compact size based on a prop, rendering several button variations.

import is, { isNot, isOr, match } from 'styled-is';
import styled from 'styled-components';
import React from 'react';
import { createRoot } from 'react-dom/client';

const ThemedButton = styled.button`
  padding: 10px 20px;
  border: none;
  border-radius: 4px;
  cursor: pointer;
  font-size: 16px;
  background-color: #eee;
  color: #333;

  ${is('primary')`
    background-color: #007bff;
    color: white;
  `};

  ${is('large')`
    padding: 15px 30px;
    font-size: 20px;
  `};

  ${isNot('disabled')`
    &:hover {
      opacity: 0.9;
    }
  `};

  ${isOr('primary', 'secondary')`
    font-weight: bold;
  `};

  ${match('variant', 'outline')`
    border: 2px solid currentColor;
    background-color: transparent;
  `};

  ${match('variant', 'text')`
    background-color: transparent;
    color: #007bff;
    padding: 5px 10px;
  `};

  ${(props) =>
    is('compact')(props) &&
    `
      padding: 5px 10px;
      font-size: 14px;
    `}
`;

function App() {
  return (
    <div>
      <ThemedButton>Default Button</ThemedButton>
      <ThemedButton primary>Primary Button</ThemedButton>
      <ThemedButton primary large>Primary Large Button</ThemedButton>
      <ThemedButton large disabled>Large Disabled Button</ThemedButton>
      <ThemedButton variant="outline" primary>Outline Primary</ThemedButton>
      <ThemedButton variant="text">Text Button</ThemedButton>
      <ThemedButton compact>Compact Button</ThemedButton>
      <ThemedButton primary compact>Primary Compact</ThemedButton>
    </div>
  );
}

const container = document.getElementById('root');
if (container) {
  const root = createRoot(container);
  root.render(<App />);
} else {
  console.error("Root element not found. Please ensure your HTML has a <div id='root'>.");
}