add useTitle

pages/docs/hooks/useTitle.mdx

@@ -0,0 +1,33 @@
+import { Meta } from 'docsComponents';
+
+<Meta title="useTitle" />
+
+# useTitle
+
+useTitle sets document title when a title is passed.
+
+## Signature
+
+```ts
+function useTitle(title?: string): void;
+```
+
+### Example
+
+Set document title with useTitle.
+
+```js live withRender
+function TitleComponent() {
+  const [title, setTitle] = useState();
+  useTitle(title);
+
+  return (
+    <>
+      <H3>Type to set document title</H3>
+      <TextInput value={title} onChange={(ev) => setTitle(ev.target.value)} />
+    </>
+  );
+}
+
+render(<TitleComponent />);
+```

pages/docs/nav.json

@@ -87,7 +87,8 @@
       "useDarkMode": "/docs/hooks/useDarkMode",
       "useFocus": "/docs/hooks/useFocus",
       "useId": "/docs/hooks/useId",
-      "useOutline": "/docs/hooks/useOutline"
+      "useOutline": "/docs/hooks/useOutline",
+      "useTitle": "/docs/hooks/useTitle"
     }
   },
   "Customizing": {

src/hooks/index.ts

@@ -3,3 +3,4 @@ export * from './useFocus';
 export * from './useId';
 export * from './useOutline';
 export * from './useTheme';
+export * from './useTitle';

src/hooks/useTitle/index.ts

@@ -0,0 +1 @@
+export { useTitle } from './useTitle';

src/hooks/useTitle/useTitle.spec.ts

@@ -0,0 +1,23 @@
+import { renderHook } from '@testing-library/react-hooks';
+import { useTitle } from './useTitle';
+
+describe('useTitle', () => {
+  beforeEach(() => {
+    document.title = 'initial title';
+  });
+
+  it('sets title', () => {
+    renderHook(() => useTitle('Hello World'));
+    expect(document.title).toBe('Hello World');
+  });
+
+  it('does not change title when no title is passed', () => {
+    renderHook(() => useTitle());
+    expect(document.title).toBe('initial title');
+  });
+
+  it('does not change title when empty string is passed', () => {
+    renderHook(() => useTitle(''));
+    expect(document.title).toBe('initial title');
+  });
+});

src/hooks/useTitle/useTitle.ts

@@ -0,0 +1,12 @@
+import { useEffect } from 'react';
+
+/**
+ * useTitle sets document title when a title is passed.
+ */
+export function useTitle(title?: string): void {
+  useEffect(() => {
+    if (title) {
+      document.title = title;
+    }
+  }, [title]);
+}