Path, Query, Hash & Params

pathAtom, qsAtom, hashAtom, paramsAtom — bidirectional writes via navigateTo.

import { html, useUtils, buildPath, renderApp } from 'mates';

const Page = () => {
  const {
    pathAtom,
    qsAtom,
    hashAtom,
    paramsAtom,
    patternsAtom,
    historyStateAtom,
    navigateTo,
  } = useUtils();

  return () => html`
    <p>path: ${pathAtom()}</p>
    <p>qs: ${JSON.stringify(qsAtom())}</p>
    <p>hash: ${JSON.stringify(hashAtom())}</p>
    <p>pattern: ${patternsAtom() ?? '(none)'}</p>
    <p>params: ${JSON.stringify(paramsAtom())}</p>
    <p>history: ${JSON.stringify(historyStateAtom())}</p>

    <button @click=${() =>
      navigateTo('/users/42?tab=bio#n=1', false, { from: 'nav' })
    }>
      Go with qs + hash + state
    </button>

    <button @click=${() =>
      navigateTo(buildPath('/users/:id', { id: 99 }))
    }>
      buildPath → /users/99
    </button>
  `;
};

renderApp(Page, document.getElementById('app'));

Overview

After navigateTo, three URL atoms stay aligned with the address bar: pathname, query object, and hash object. paramsAtom also needs the matched route pattern.

Writes are bidirectional: pathAtom.set / qsAtom.set / paramsAtom.set call navigateTo (with different default replace flags). Prefer navigateTo when setting path and query together.

Which atom for what

Atom	Holds	Write default
`pathAtom`	pathname only	`replace` defaults to `false` (push).
`qsAtom`	query object	`replace` defaults to `true`.
`hashAtom`	hash object	`replace` defaults to `true`.
`paramsAtom`	:param values	Needs `patternsAtom`; rebuilds path on write.
`patternsAtom`	matched pattern	Set by `Router` / `animatedRouter`.

path + query (two destinations)

navigateTo syncs pathAtom and qsAtom. Tiny two-route demo.

import { html, useUtils, renderApp } from 'mates';

const App = () => {

const { pathAtom, qsAtom, navigateTo } = useUtils();

return () => html`

<span class="card-title">${pathAtom()}</span>

</div>

<span class="overline">query</span>

${Object.keys(qsAtom()).length ? JSON.stringify(qsAtom()) : '(none)'}

</span>

</div>

<button class="btn-ghost" @click=${() => navigateTo('/')}>Home</button>

<button class="btn-ghost" @click=${() => navigateTo('/about?tab=bio')}>

About?tab=bio

</button>

</div>

<p class="hint">Atom writes also navigate: pathAtom.set('/about')</p>

</div>

};

renderApp(App, document.getElementById('app'));

paramsAtom with Router

Two routes: / and /users/:id. patternsAtom + paramsAtom update on match.

import { html, Router, useUtils, renderApp } from 'mates';

const Home = () => () => html`<p class="muted">Home</p>`;

const User = () => {

const { paramsAtom } = useUtils();

return () => html`<p class="muted">User #${paramsAtom().id ?? '?'}</p>`;

};

const App = () => {

const { navigateTo, paramsAtom, patternsAtom } = useUtils();

const outlet = Router([

{ path: '/', component: Home },

{ path: '/users/:id', component: User },

]);

return () => html`

<button @click=${() => navigateTo('/')}>Home</button>

<button class="btn-primary" @click=${() => navigateTo('/users/7')}>/users/7</button>

</div>

<p class="hint">pattern=${patternsAtom() ?? '—'} params=${JSON.stringify(paramsAtom())}</p>

${outlet}

</div>

};

renderApp(App, document.getElementById('app'));

API — URL atoms & helpers

import { useUtils, buildPath, isPathMatching } from 'mates'

Prop / Option	Type	Default	Description
`pathAtom()`	`string`	—	Current pathname only. .set(path, replace?) / .update(fn, replace?) call navigateTo — replace defaults to false (push).
`qsAtom()`	`Record`	—	Parsed query object. .set / .update call navigateTo — replace defaults to true.
`hashAtom()`	`Record`	—	Parsed hash object. .set / .update take optional replace (default true).
`paramsAtom()`	`Record`	—	Dynamic :param values for the matched pattern. .set / .update rebuild via buildPath + navigateTo (replace default true).
`patternsAtom()`	`string \| null`	—	Matched route pattern, set by Router / animatedRouter.
`historyStateAtom()`	`unknown`	—	Mirrors history.state from navigateTo / popstate.
`buildPath(pattern, params)`	`string`	—	Fill :param segments.
`isPathMatching(pattern)`	`boolean`	—	Whether pathAtom matches the pattern.

Atom write defaults (bidirectional)

Prop / Option	Type	Default	Description
`pathAtom.set / .update`	`replace = false`	—	Defaults to push (new history entry).
`qsAtom / hashAtom / paramsAtom .set / .update`	`replace = true`	—	Defaults to replace so edits do not spam history.