import { Meta } from '@storybook/addon-docs';
import EditPage from 'Storybook/components/EditPage';

<Meta title="Hooks/README" />

# Hooks

The Hooks directory contains all of the [React hooks][hooks] provided by this
library. Hooks let you tap into some stateful behavior of components,
maintaining information across renders of the same component. If you're new to
hooks, you should peruse some of React's official documentation, but the most
important things to know are that if you call any hooks in a component, you
_have_ to call all the same hooks in exactly the same order _every_ time that
component renders. That means you should never call a hook conditionally (like
in an `if` block or a ternary) and you should never call a hook after an early
return.

All of our general-purpose hooks are in the top level of the Hooks directory,
but some groups of hooks are organized in subdirectories. Mostly, these are
hooks that are closely tied to parts of our front-end data store, like our
breakpoint hooks. This organization is only intended to make the codebase a bit
more navigable; they're all still hooks and you use them all in the same way.

## How to use our hooks documentation

Each hook includes a documentation page in Storybook, made up of one or more
stories. (If you're new to Storybook, "story" is its term for a live,
interactive example of something being used.) If you look at the top of this
page, you should see two tabs: "Canvas" and "Docs". The Canvas tab will allow
you to isolate a single story, while the Docs tab will allow you to see all of
a hook's stories on one page and read the accompanying prose documentation.

In general, each hook's Docs page starts with a general explanation of what the
hook does and a basic example. Below that, you'll find a table listing each
argument that the hook accepts, annotated with its type, its default value, and
a description of what it does. If you're trying to figure out _everything_
a single hook can do, that's the best place to look. Below the arguments table,
there's usually a set of additional stories that demonstrate different specific
uses of the hook or how it behaves with different inputs. The code for each
story is expanded by default, because, unlike components, the _code_ is
generally much more useful and informative than the rendered story.

[hooks]: https://react.dev/reference/react

<EditPage page={STORYBOOK_FILE_PATH} />
