feat: add new hook useDocumentTitle

README.md

@@ -101,6 +101,7 @@
   - [`useCookie`](./docs/useCookie.md) — provides way to read, update and delete a cookie. [![][img-demo]](https://streamich.github.io/react-use/?path=/story/side-effects-usecookie--demo)
   - [`useCopyToClipboard`](./docs/useCopyToClipboard.md) — copies text to clipboard.
   - [`useDebounce`](./docs/useDebounce.md) — debounces a function. [![][img-demo]](https://streamich.github.io/react-use/?path=/story/side-effects-usedebounce--demo)
+  - [`useDocumentTitle`](./docs/useDocumentTitle.md) — changes document title.
   - [`useError`](./docs/useError.md) — error dispatcher. [![][img-demo]](https://streamich.github.io/react-use/?path=/story/side-effects-useerror--demo)
   - [`useFavicon`](./docs/useFavicon.md) — sets favicon of the page.
   - [`useLocalStorage`](./docs/useLocalStorage.md) — manages a value in `localStorage`.

docs/useDocumentTitle.md

@@ -0,0 +1,31 @@
+# `useDocumentTitle`
+
+React hook that updates the `document.title` when the component mounts or when the title changes.  
+It also restores the previous title on unmount.
+
+## Usage
+
+```jsx
+import { useDocumentTitle } from 'react-use';
+
+const Demo = () => {
+  const [count, setCount] = React.useState(0);
+
+  useDocumentTitle(`Clicked ${count} times`);
+
+  return (
+    <div>
+      <h3>Click the button to update document title</h3>
+      <button onClick={() => setCount(c => c + 1)}>
+        Clicked {count} times
+      </button>
+    </div>
+  );
+};
+```
+
+## Reference
+
+```ts
+useDocumentTitle(title);
+```

src/index.ts

@@ -18,6 +18,7 @@ export { default as useCustomCompareEffect } from './useCustomCompareEffect';
 export { default as useDebounce } from './useDebounce';
 export { default as useDeepCompareEffect } from './useDeepCompareEffect';
 export { default as useDefault } from './useDefault';
+export { default as useDocumentTitle } from './useDocumentTitle';
 export { default as useDrop } from './useDrop';
 export { default as useDropArea } from './useDropArea';
 export { default as useEffectOnce } from './useEffectOnce';

src/useDocumentTitle.ts

@@ -0,0 +1,12 @@
+import { useEffect } from 'react';
+
+export default function useDocumentTitle(title: string) {
+  useEffect(() => {
+    const previousTitle = document.title;
+    document.title = title;
+
+    return () => {
+      document.title = previousTitle;
+    };
+  }, [title]);
+}

stories/useDocumentTitle.story.tsx

@@ -0,0 +1,22 @@
+import { storiesOf } from '@storybook/react';
+import * as React from 'react';
+import { useDocumentTitle } from '../src';
+import ShowDocs from './util/ShowDocs';
+
+const Demo = () => {
+  const [count, setCount] = React.useState(0);
+
+  // Update document title whenever count changes
+  useDocumentTitle(`Clicked ${count} times`);
+
+  return (
+    <div>
+      <h3>Click the button to update document title</h3>
+      <button onClick={() => setCount((c) => c + 1)}>Clicked {count} times</button>
+    </div>
+  );
+};
+
+storiesOf('SideEffects/useDocumentTitle', module)
+  .add('Docs', () => <ShowDocs md={require('../docs/useDocumentTitle.md')} />)
+  .add('Demo', () => <Demo />);

tests/useDocumentTitle.test.ts

@@ -0,0 +1,22 @@
+import { renderHook } from '@testing-library/react-hooks';
+import { useDocumentTitle } from '../src';
+
+it('should set the document title on mount', () => {
+  const title = 'Doc Title';
+
+  renderHook(() => useDocumentTitle(title));
+
+  expect(document.title).toBe(title);
+});
+
+it('should update the title when argument changes', () => {
+  const { rerender } = renderHook(({ title }) => useDocumentTitle(title), {
+    initialProps: { title: 'First Title' },
+  });
+
+  expect(document.title).toBe('First Title');
+
+  rerender({ title: 'Second Title' });
+
+  expect(document.title).toBe('Second Title');
+});