use-viewport's Introduction

🌅 useViewport()

useViewport() provides a hook with the current window size and convenient functions to help building responsive apps.

Usage

Add it to your project:

yarn add use-viewport

Use it in your React app:

// App.js

import React from 'react'
import { ViewportProvider, useViewport } from 'use-viewport'

function App() {
  return (
    <ViewportProvider>
      <h1>useViewport</h1>
      <ViewportSize />
    </ViewportProvider>
  )
}

function ViewportSize() {
  const { width, height, within, below, above } = useViewport()

  return (
    <div>
      {below('medium') && <div>small</div>}
      {within('medium', 'large') && <div>medium</div>}
      {above('large') && <div>large</div>}
      <p>
        Current screen width is {width}px and the height is {height}px
      </p>
    </div>
  )
}

export default App

API

<ViewportProvider />

This is the provider component. It should be placed above any component using useViewport().

Apart from children it accepts the following props:

throttle

The interval in ms for window updates. Defaults to 100.

useViewport()

This is the hook to be used throughout the app.

It takes no parameters and returns the following:

width: The current screen width.
height: The current screen height.
within(min, max): A function that returns true if the viewport width is between min and max. min and max can be any number, or one of the available breakpoints. If -1 is passed as min or max, there will be no minimum or maximum.
above(x): Returns true if the viewport width is above x, false otherwise.
below(x): Returns true if the viewport width is below x, false otherwise.
breakpoints: An object that contains the number values of the different recommended breakpoints. It can be useful to set these values in CSS, for example.

use-viewport's People

Contributors

Stargazers

Watchers

use-viewport's Issues

Provide option to supply own breakpoints

Virtual viewports

It could be useful to have the possibility to declare viewport contexts, or virtual viewports. It would make it possible for components to react to either the global viewport or a local one.

For example, let’s imagine an app with two panels: a menu and a main screen.

Some components in the main screen would always use to the global viewport G, like a popover or a modal, so they can position themselves over the menu panel. But some others, like layout breakpoints in the main screen, would need to know the dimensions of their local viewport L, which is the right panel.

A way to do this could be to declare it all in ViewportProvider:

// App.js

const MENU_PANEL_WIDTH = 300

function App() {
  return (
    <ViewportProvider
      viewports={{
        // Local viewports could be declared as callbacks
        // that would receive the main viewport dimensions.
        main: ([ width, height ]) => [ width - MENU_PANEL_WIDTH, height ],
      }}
    >
      <PanelsLayout
        menu={/* … */}
        main={
          <MyLocalComponent />
        }
      />
    </ViewportProvider>
  )
}

// MyLocalComponent.js

function MyLocalComponent() {
  const viewport = useViewport()
  const mainPanelViewport = useViewport('main')

  // …
}

Another way would be to nest the ViewportProvider components. That might be useful to prevent having to move all the information at the level of the single ViewportProvider element. At this point, I think it would make sense to also rename the component Viewport (as in “declares a viewport”).

// App.js

function App() {
  return (
    <Viewport>
      <PanelsLayout
        menu={/* … */}
        main={
          <MyLocalComponent />
        }
      />
    </Viewport>
  )
}

// PanelsLayout.js

const MENU_PANEL_WIDTH = 300

function PanelsLayout({ menu, main }) {
  return (
    <div style={{ display: 'flex', width: '100%' }}>
      <div style={{ flexShrink: '0', width: `${MENU_PANEL_WIDTH}px` }}>
        {menu}
      </div>
      <div style={{ flexGrow: '1' }}>
        <Viewport
          name="main"
          size={([ width, height ]) => [ width - MENU_PANEL_WIDTH, height ]}
        >
          {main}
        </Viewport>
      </div>
    </div>
  )
}

// MyLocalComponent.js

function MyLocalComponent() {
  const viewport = useViewport()
  const mainPanelViewport = useViewport('main')

  // …
}

Finally, it might also be useful to declare the coordinates of these viewport. Rather than an array with two entries, we could accept an object containing the x and y coordinates. These would get returned by the useViewport() function as x and y, and be 0 for the global viewport.

Note: this feature would let us deprecate the useLayout() hook in aragonUI to use useViewport() directly.

@Evalir @sohkai let me know what you think!

Recommend Projects

aragon / use-viewport Goto Github PK

use-viewport's Introduction

🌅 useViewport()

Usage

API

<ViewportProvider />

throttle

useViewport()

use-viewport's People

Contributors

Stargazers

Watchers

Forkers

use-viewport's Issues

Provide option to supply own breakpoints

Virtual viewports

Recommend Projects

React

Vue.js

Typescript

TensorFlow

Django

Laravel

D3

Recommend Topics

javascript

web

server

Machine learning

Visualization

Game

Recommend Org

Facebook

Microsoft

Google

Alibaba

D3

Tencent