react-window-context
v1.0.0-beta.1
Published
A react Provider with hook to get viewport info and subscribe to changes.
Downloads
8
Readme
react-window-context
A React provider to track and update on changes to the window, screen, and/or visual viewport.
Install
npm i react-window-context
Usage
Use the WindowContext
context provider to track and react to updates on window
, screen
, and visualViewport
objects. Exactly what is tracked is controlled by the plugins loaded see the API reference for makeWindowPlugin()
and friends. All the non-component functions except useWindowInfo
are used to create plugins or a set of plugins.
import React from 'react'
import { allWindowPlugins, useWindowInfo, WindowContext } from 'react-window-context'
// This will track all attributes of the 'window' object (innerWidth, innerHeight, outerWidth, etc.)
const plugins = allWindowPlugins()
const WindowInfo = () => {
const windowInfo = useWindowInfo()
return (
<div style={style}>
{JSON.stringify(viewportInfo.window, null, ' ')}
</div>
)
}
return (
<WindowContext plugins={plugins}>
<WindowInfo />
</WindowContext>
)
API Reference
API generated with dmd-readme-api.
- Constants:
VALID_SCREEN_ATTRIBUTES
: Object defining the validscreen
attributes.VALID_VISUAL_VIEWPORT_ATTRIBUTES
: Object defining the validvisualViewport
attributes.VALID_WINDOW_ATTRIBUTES
: Object defining the validwindow
attributes.
- Functions:
allPlugins()
: Convenience method to track all data forwindow
,screen
, andvisualViewport
.allScreenPlugins()
: Convenience method to create allscreen
related plugins.allVisualViewportPlugins()
: Convenience method to create allvisualViewport
related plugins.allWindowPlugins()
: Convenience method to create allscreen
related plugins.breakpointPlugin()
: Plugin to track whether the current theme 'breakpoint' and whether it has changed or not.makeScreenPlugin()
: Function to generate plugins to extractscreen
related data.makeVisualViewportPlugin()
: Function to generate plugins to extractvisualViewport
related data.makeWindowPlugin()
: Function to generate plugins to extractwindow
related data.useWindowInfo()
: Retrivees the trackedwindow
/screen
/visualViewport
data.WindowContext()
: A context component that tracks information from thewindow
and related objects.
VALID_SCREEN_ATTRIBUTES
Object defining the valid screen
attributes. Also defines associated events that might cause a change in the value
of each attribute. Refer to source code for list of supported attributes.
VALID_VISUAL_VIEWPORT_ATTRIBUTES
Object defining the valid visualViewport
attributes. Also defines associated events that might cause a change in
the value of each attribute. Refer to source code for list of supported attributes.
VALID_WINDOW_ATTRIBUTES
Object defining the valid window
attributes. Also defines associated events that might cause a change in the
value of each attribute. Refer to source code for list of supported attributes.
allPlugins()
⇒ Array.<function()>
Convenience method to track all data for window
, screen
, and visualViewport
.
Returns: Array.<function()>
- An array of WindowContext plugins.
See: allWindowPlugins for an example.
allScreenPlugins()
⇒ Array.<function()>
Convenience method to create all screen
related plugins.
Returns: Array.<function()>
- An array of WindowContext plugins.
See: allWindowPlugins for an example.
allVisualViewportPlugins()
⇒ Array.<function()>
Convenience method to create all visualViewport
related plugins.
Returns: Array.<function()>
- An array of WindowContext plugins.
See: allWindowPlugins for an example.
allWindowPlugins()
⇒ Array.<function()>
Convenience method to create all screen
related plugins.
Returns: Array.<function()>
- An array of WindowContext plugins.
Example
const allWindowPlugins = allWindowPlugins()
return (
<WindowContext plugins={allWindowPlugins}>
<DisplayAllWindowData />
</WindowContext>
)
breakpointPlugin(prevInfo, newInfo, getTheme)
⇒ boolean
Plugin to track whether the current theme 'breakpoint' and whether it has changed or not. This method works with
with Material UI themes or any theme that provide a breakpoint
definition (see
example). Note, the typical breakpoints are 'xs', 'sm', 'md', 'lg', 'xl', but in practice can be anything.
| Param | Type | Description |
| --- | --- | --- |
| prevInfo | object
| The info object last time the plugin was invoked. |
| newInfo | object
| The info object, to be updated by the method, for this invocation. |
| getTheme | function
| A function to retrieve the current theme. |
Returns: boolean
- true
if the width has changed and false
otherwise.
Example
const getTheme = () => ({
breakpoints: {
values: {
key1: 0, // cuttoff in pixels above which the breakpoint is activated
key2: 100,
}
}
})
const info = { windew: { innerWidth: 100 }}
const newInfo = structuredClone(info)
console.log(breakpointPlugin(info, newInfo, getTheme)) // prints: 'key2'
makeScreenPlugin(attribute)
⇒ function
Function to generate plugins to extract screen
related data.
| Param | Type | Description |
| --- | --- | --- |
| attribute | string
| The screen
attribute to track. |
Returns: function
- A WindowContext plugin.
Throws: Function to generate plugins to extract screen
related data.
See:
- VALID_SCREEN_ATTRIBUTES for valid attributes.
- makeWindowPlugin for an example.
makeVisualViewportPlugin(attribute)
⇒ function
Function to generate plugins to extract visualViewport
related data.
| Param | Type | Description |
| --- | --- | --- |
| attribute | string
| The visualViewport
attribute to track. |
Returns: function
- A WindowContext plugin.
Throws: Function to generate plugins to extract visualViewport
related data.
See:
- VALID_VISUAL_VIEWPORT_ATTRIBUTES for valid attributes.
- makeWindowPlugin for an example.
makeWindowPlugin(attribute)
⇒ function
Function to generate plugins to extract window
related data.
| Param | Type | Description |
| --- | --- | --- |
| attribute | string
| The window
attribute to track. |
Returns: function
- A WindowContext plugin.
Throws: Function to generate plugins to extract window
related data.
Example
const innerHeightPlugin = makeWindowPlugin('innerHeight')
return (
<WindowContext plugins={[innerHeightPlugin]}>
<DisplayInnerHeight />
</WindowContext>
)
See: VALID_WINDOW_ATTRIBUTES for valid attributes.
useWindowInfo()
⇒ object
Retrivees the tracked window
/screen
/visualViewport
data.
Returns: object
- The information object, which has three properties: window
, screen
, and visualViewport
. Any
tracked attributes are available on the corresponding property. E.g, the window
's inner height is availablee on
window.innerHeight
, etc.`
WindowContext(attr)
⇒ object
A context component that tracks information from the window
and related objects.
The exact information tracked is determanide by the plugins passed to the component. You can use the breakpointPlugin directly or use makeScreenPlugin or one of the related makePluginX
or group plugin
methods to generate plugins for specific data.
The pollInterval
is used when tracking window.screenX
/screenY
(or their aliases, screenLeft
and
screenTop
). Because there is no event that tells us when the browser window (as a whole) is dragged around, we
have to check it's position periodically.
| Param | Type | Description |
| --- | --- | --- |
| attr | object
| The atributes + children hash object. |
| [attr.getTheme] | function
| A function to retrieve the current theme. This is used by module:react-viewport-context.breakpointPlugin and required if that (or another custom plugin utilizing the theme) is used. |
| attr.plugins | Array.<function()>
| An array of plugin functions which determine what data is extracted (and what data determines the update cycle). |
| [attr.pollInterval] | number
| The amount of time in ms to wait between polling for the window location (see function description). |
| attr.children | object
| The child elements passed in from the content of the component. |
Returns: object
- The rendered component.
Contributing
Plase feel free to submit any bug reports or feature suggestions. You're also welcome to submit patches of course. We don't have a full contributors policy yet, but you can post questions on our discord channel. It's not monitored 24/7, but you should hear back from us by next business day generally.
Support
The best way to get free support is to submit a ticket. You can also become a patron for as little as $1/month and get priority support and input into new feature on all Liquid Labs open source software. You can get these benefits and support our work at patreon.com/zanecodes.