A collection of standalone ES6 ReactJS utilities and hooks, written in TypeScript and transpiled to and bundled in ES5.
This ES5 module is distributed via npm and should be installed as a production dependency.
Using yarn (preferred)
yarn add -E k2-react-utils
or via npm
npm i -S -E k2-react-utils
Note: react@^16.8.0 would be required when using hook utils.
Type definitions come bundled in.
k2-react-utils barrels (re-exports) the following utils and hooks as named exports:
<Content/> - source
A component that performs HTML sanitization.
Dependencies: react, react-dom
| Props | Type | Description |
|---|---|---|
| text | string (required) | Returns a DOM node with a <span/> wrapper |
import * as React from "react"; // standard TypeScript syntax
import { Content } from "k2-react-utils";
const Post: React.FunctionComponent<{}> = () => {
const stringifiedMarkup: string =
"<p>A Lion from Lannisport, and the sheep from the North</p>";
return <Content text={stringifiedMarkup} />; // returns a DOM node
};classify - source
A function that takes in an object of classes along with conditionals, and returns a string of classnames
Dependencies: none
| Parameters | Type | Description |
|---|---|---|
| classObject | Object (required) | - |
import * as React from "react"; // standard TypeScript syntax
import { classify } from "k2-react-utils";
const MyComponent: React.FunctionComponent<{}> = () => {
const classNames = classify({
"js-active": true,
"js-focus": false
}); // returns "js-active"
return <div className={classNames} />;
};Alternatives
- This util would be helpful when to working imperively with CSS classes, example when authoring libraries.
styled-componentsis a much preferred alternative when styling React components.
connect - source
A re-implementation of react-redux's connect which suppresses @types/react-redux issues when using connect as a decorator to connect class components in TypeScript 2/3.
Dependencies: react, react-dom, react-redux
See connect's parameters here: https://react-redux.js.org/api/connect#connect-parameters
import * as React from 'react'; // standard TypeScript syntax
import { connect } from 'k2-react-utils';
import { IAppState, ILocale } from './models';
interface IStateProps{
locale: ILocale
}
@connect((state: IAppState)=>({
locale: state.locale
}))
class MyComponent: React.Component<IStateProps>{
render(){
const {locale}=this.props;
return <div>{locale.region}<div/>;
}
}Alternatives
- With
react-redux@7.0.0comes theuseSelectorhook which with less effort connect to yourreduxstore. - The
@connectutil would be ideal when working with stateful class components that would need to be connected to the store.
deviceService - source
A service that identifies the device's current browser, operating system or platform (desktop or mobile) via three getters; getBrowserName, getOperatingSystem, getPlatform.
import * as React from "react"; // standard TypeScript syntax
import {
getBrowserName,
getOperatingSystem,
getPlatform
} from "k2-react-utils";
getBrowserName(); // sample, "chrome"
getOperatingSystem(); // sample, "windows"
getPlatform(); // sample, "desktop"fontUnitConverter (convertPixelsToRem, convertPixelsToEm) - source
A utility that converts pixels to rem/em units.
Dependencies: none
| Paramters | Type | Description |
|---|---|---|
| pixelValue | string (required) | Value to be converted into em/rem unitls |
| baseFontSize | string (optional) - default '16px' | root pixel value, set on the <html> or <body> tag |
// font-settings
import { convertPixelsToRem, convertPixelsToEm } from 'k2-react-utils';
// either
const fontSizes = {
f16: convertPixelsToRem('16px', '10px');
f20: convertPixelsToRem('20px', '10px');
};
// or for ems
const fontSizes = {
f16: convertPixelsToEm('16px');
f18: convertPixelsToEm('18px');
};
// Styled Component
import styled from 'styled-components';
import { fontSizes } from './fontSettings';
const MyComponent = styled`
font-size: ${fontSizes.f16}; // DOM output => font-size: 1.6rem;
`;hostEnv - source
A util that returns an object denoting the current hostname and a boolean value, isLocal.
Dependencies: none
| Paramters | Type | Description |
|---|---|---|
| host | string (optional), default window.location.host |
- |
import * as React from "react"; // standard TypeScript syntax
import { hostEnv } from "k2-react-utils";
const MyComponent: React.FunctionComponent<{}> = () => {
React.useEffect(() => {
window.fetch(getUrl());
}, []);
const getUrl = (): string => {
if (hostEnv.isLocal) {
return "http//dev.somesite.com/api/people";
} else if (hostEnv.host === "uat1.somesite.com") {
return "http//uat.somesite.com/api/people";
}
return "/api/people";
};
return <div />;
};Alternatives
- Consider using client-side environment variables configurable via an
.envfile.
convertXmlToJson - source
A function that converts xml into json.
Dependencies: xml-js
| Parameters | Type | Description |
|---|---|---|
| xmlNode | xml (required) | - |
import { convertXmlToJson } from "k2-react-utils";
const xmlNode = `<xml>
<title>Aerys</title>
</xml>`;
convertXmlToJson(xmlNode);useBrowserStorage - source
A hook that performs getting, setting and clearing of values to localStorage and sessionStorage.
Dependencies: react, react-dom
| Parameters | Type | Description |
|---|---|---|
| storageType | 'LOCAL' | 'SESSION' (required) | context, point to localStorage, or sessionStorage |
| key | string | number | boolean (required) | property name to used in either local or session storage |
import * as React from "react"; // standard TypeScript syntax
import { useEffect } from "react";
import { useBrowserStorage } from "k2-react-utils";
const MyComponent: React.FunctionComponent<{}> = () => {
const [isUndead, setIsUndead, clearIsUndead] = useBrowserStorage<boolean>(
"SESSION",
"isUndead"
);
useEffect(() => {
setIsUndead(false);
() => {
clearIsUndead();
};
}, []);
return <div>Xhoan Daxos is Undead: {isUndead}</div>;
};useDevice - source
A hook that identifies the device's current browser, operating system or platform (desktop or mobile).
Dependencies: react
import * as React from "react"; // standard TypeScript syntax
import { useDevice } from "k2-react-utils";
const MyComponent: React.FunctionComponent<{}> = () => {
const { browserName, operatingSystem, platform } = useDevice();
return (
<table>
<tbody>
<tr>
<td>Browser</td>
<td>{browserName}</td> // sample, "chrome"
</tr>
<tr>
<td>OS</td>
<td>{operatingSystem}</td> // sample, "windows"
</tr>
<tr>
<td>OS</td>
<td>{platform}</td> // sample, "desktop"
</tr>
</tbody>
</table>
);
};useScroll - source
A hook that returns the y-position (integer) on scroll.
Dependencies: react, react-dom
import * as React from "react"; // standard TypeScript syntax
import { useScroll } from "k2-react-utils";
const MyComponent: React.FunctionComponent<{}> = () => {
const { verticalScrollPosition } = useScroll();
return <div>Vertical scroll position {verticalScrollPosition}</div>; // 0
};useViewport - source
A hook that returns the current viewport's width, height and the document's scrollable height (as integers).
Dependencies: react, react-dom
import * as React from "react"; // standard TypeScript syntax
import { useViewport } from "k2-react-utils";
const MyComponent: React.FunctionComponent<{}> = () => {
const { viewportWidth, viewportHeight, documentHeight } = useViewport();
return (
<div>
width: {viewportWidth}, height: {viewportHeight}, documentHeight:{" "}
{documentHeight},
</div>
);
};- Run
yarnon the root of the repository. - Run
yarn startto start the project. - Run
yarn test:watchto ammend tests.