Add "useBreakpoint" hook

This is an API refinement story preparation for the first major release. It introduces a breaking change and will be released respectively.

What:

I suggest to add the following React hook:

type UseBreakpoint<T> = ((breakpointName: string) => T) => [string, T]

Why:

It should replace current useBreakpointChange hook with both:

1. Information about the current breakpoint (first argument in a tuple),
2. Updater function that is called on each breakpoint change (mirroring of useBreakpointChange.
3. useBreakpoint will be called on initial render, when useBreakpointChange is not.

Main motivation is that it’s currently lengthy to know which breakpoint is met. It requires to have useState updating its value on useBreakpointChange callback. With the suggested hook added it can be written in a single hook declaration.

Usage example:

Getting a breakpoint name

import { useBreakpoint } from 'atomic-layout'

const Component = () => {
  const [breakpointName] = useBreakpoint()
  return <p>You are on {breakpointName} screen</p>
}

Reacting to breakpoint change

import { useBreakpoint } from 'atomic-layout'

const dataMap = {
  xs: 'one',
  sm: 'two'
}

const Component = () => {
  const [breakpointName, data] = useBreakpoint((breakpointName) => {
    return dataMap[breakpointName]
  })
  return <p>You are on {breakpointName} screen with {data}</p>
}

How:

• Deprecate useBreakpointChange
• Add useBreakpoint
• Add unit tests

[kettanaito]

@vitordino, you have a point. While reading your reply I’ve also realized that useCurrentBreakpoints has a slightly different behavior than useResponsiveQuery. I’ll elaborate below.

useResponsiveQuery

Designed to determine a viewport match against a breakpoint, or a range of breakpoints. More precisely, a range of breakpoints of the same nature (i.e. dimensional, orientational, or pixel density breakpoints). With this hook you cannot, say, get the match in case you would like to know if it’s a medium breakpoint or a retina display. You would have to use such hook twice:

const isMedium = useResponsiveQuery({ for: 'md' })
const isRetina = useResponsiveQuery({ for: 'retina' })

Usage example above assumes you have got two breakpoints defined: md and retina, using Layout.configure({}).

useCurrentBreakpoints

This hook, on the other hand, returns the list of all breakpoints that match the current viewport. Breakpoints in the list may be of a different nature.

Taking the same md/retina example above, you could get the match information in a single useCurrentBreakpoints hook call:

const breakpoints = useCurrentBreakpoints()

if (breakpoints.includes('md') && breakpoints.includes('retina')) {
  // do something
}

This does not necessarily mean that this is a more performant method, as useResponsiveQuery() establishes a matchMedia() only against a breakpoint or a range you’ve provided, while useCurrentBreakpoint checks if any declared Layout.options.breakpoints math the current viewport.

Conclusion

I believe that both hook have a place to be. I’d love for the users to give them a try and see what are the use cases for both. I’ve prepared the implementation for useCurrentBreakpoints in #318, and will continue on it, since my original question was answered.

[vitordino]

yep, you caught one idea of using an array on useBreakpoints… i think it’s just a different way to express it, and maybe use it…

i’m not agains the from/to (or below/above) approaches, i even think that probably it’s more powerful too, but i believe both API’s can live simultaneously…

just some other ways to let users of the lib explore the api (some will prefer only using one of it, but maybe there are best uses for both) 🤷