#Primitives

#useNavigate

Hook that returns a function to programmatically navigate between routes.

Type:

useNavigate(): (href: string, options?: NavigateOptions) => void

Parameters:

• href: The destination path, can include query strings
• options: Optional configuration
  • relative: If false, navigates to the absolute path without relative base. Defaults to true
  • replace: If true, replaces the current history entry
  • noScroll: If true, prevents scrolling to top when navigating
  • state: Optional state object to pass to history.state, defaults to null

Example:

function NavigationComponent() {
  const navigate = useNavigate()

  return (
    <>
      <button onClick={() => navigate('/')}>Home</button>
      <button onClick={() => navigate('/products', { relative: false })}>
        Products
      </button>
      <button onClick={() => navigate('/login', { replace: true })}>
        Login
      </button>
      <button onClick={() => navigate('/details', { noScroll: true })}>
        View Details (No Scroll)
      </button>
      <button onClick={() => navigate('/search?q=zess&page=1')}>
        Search Zess (Page 1)
      </button>
      <button onClick={() => navigate('/checkout', { state: { userId: 1 } })}>
        Proceed to Checkout
      </button>
    </>
  )
}

#useSearchParams

Hook that provides access to search parameters and a function to update them.

Type:

useSearchParams(): [SearchParams, (params: Record<string, any>, options?: SearchParamsOptions) => void]

Returns: An array containing

• searchParams: A reactive object with current search parameters that auto-updates when location.search changes or when modified via setSearchParams
• setSearchParams: A function to update search parameters
  • params: Search parameters to merge with existing ones. Setting a property value to undefined, null or an empty string removes that property
  • options: Optional configuration object
    • replace: Optional flag to replace the current history entry instead of pushing a new one
    • state: Optional state object to pass to history.state, defaults to null

Example:

function ProductFilter() {
  const [searchParams, setSearchParams] = useSearchParams()
  const setCategory = (category) => setSearchParams({ category })
  const search = (keyword, searchType) => {
    setSearchParams(
      { keyword },
      {
        replace: true,
        state: { searchType },
      },
    )
  }
  const clearFilters = () => {
    setSearchParams({ category: undefined, keyword: undefined })
  }

  return (
    <div>
      <p>Current category: {searchParams.category || 'All'}</p>
      <p>Search keyword: {searchParams.keyword || 'None'}</p>
      <button onClick={() => setCategory('shoes')}>Set Category</button>
      <button onClick={() => search('sale', 'quick')}>Search with Type</button>
      <button onClick={clearFilters}>Clear Filters</button>
    </div>
  )
}

#useBeforeLeave

Hook that registers a listener to be called before leaving the current route. This allows you to intercept navigation attempts and potentially prevent them, for example, to warn users about unsaved changes.

Type:

useBeforeLeave(listener: RouteGuardListener): void

Parameters:

• listener: A function that will be called with a RouteGuardEvent object when navigation away from the current route is attempted
  • event: The route guard event object containing:
    • to: The destination path being navigated to
    • from: The current path being navigated from
    • options: Navigation options including relative, replace, and noScroll
    • defaultPrevented: Boolean indicating if the navigation has been prevented
    • preventDefault: Function to call to prevent the navigation
    • retry: Function to retry the navigation later, with an optional force parameter to bypass guards

Example:

function FormEditor() {
  const [hasUnsavedChanges, setHasUnsavedChanges] = useSignal(false)
  useBeforeLeave((event) => {
    if (hasUnsavedChanges()) {
      const confirmed = window.confirm(
        'You have unsaved changes. Are you sure you want to leave?',
      )
      if (!confirmed) {
        event.preventDefault()
      }
    }
  })

  return (
    <div>
      <input type="text" onChange={() => setHasUnsavedChanges(true)} />
      <button onClick={() => setHasUnsavedChanges(false)}>Save</button>
    </div>
  )
}

#useLocation

Hook that returns a reactive Location object containing information about the current URL. This object automatically updates when the URL changes.

Type:

useLocation(): Location

Returns: A reactive Location object with pathname and other properties

• pathname: The path portion of the URL excluding the query string
• search: The query string portion of the URL
• hash: The hash portion of the URL including the # symbol
• state: The state object associated with the current history entry passed via useNavigate or <Link> component
• query: A reactive object containing all query parameters of the URL

Example:

function LocationDisplay() {
  const location = useLocation()

  return (
    <div>
      <h2>Current Location Information</h2>
      <p>pathname: {location.pathname}</p>
      <p>search: {location.search}</p>
      <p>hash: {location.hash}</p>
      <p>state: {JSON.stringify(location.state)}</p>
      <p>query: {JSON.stringify(location.query)}</p>
    </div>
  )
}