useRefinements

This composable is part of the refining feature. It takes a Refinement property as a parameter and exposes methods to refine a query using filters and sorts.

Related	Refining

Usage

function useRefinements<
  Properties extends object,
  RefinementsKey extends keyof Properties
>(
  properties: Properties,
  refinementsKey: RefinementsKey,
  defaultOptions: HybridRequestOptions = {}
)

useRefinements accepts the view's $props object as its first parameter and the name of the Refinement object's property as the second. As its optional third parameter, it accepts a list of request options.

Example

const $props = defineProps<{
  users: Paginator<App.Data.UserData>
  refinements: Refinements
}>()

const refine = useRefinements($props, 'refinements')

Returned object

The object returned by useRefinements contains a few functions and properties that are used to refine the affected query.

All of the functions below accept additional request options as their last parameter.

sorts

• Type: see the sorts array.

The list of available sorts. They are configured by the Refine object in the back-end.

filters

• Type: see the filters array.

The list of available filters. They are configured by the Refine object in the back-end.

bindFilter

• Type: <T>(name: string, options?: BindOptions) => Ref<T>

Binds the given filter to a ref. The second parameter, options, accepts an alternative watch function and a debounce property that defaults to 250 milliseconds.

Example

const commercial = refine.bindFilter<bool>('commercial')
const search = refine.bindFilter<string>('search')

toggleSort

• Type: Function
• Parameters: sortName: string

Toggles the specified sort. ToggleSortOptions is the same as HybridRequestOptions with an additional direction property, which must be undefined, asc or desc. If specified, the sort will be applied as such.

applyFilter

• Type: Function
• Parameters: filter: string, value: any

Applies the specified value to the specified filter.

isFiltering

• Type: Function

Determines whether the specified filter is active.

clearFilter

• Type: Function
• Parameters: filter: string

Clears the specified filter.

clearFilters

• Type: Function

Clears all active filters.

isSorting

• Type: Function

Toggles the specified sort. The second parameter accepts a direction property that specifies the direction of the sort.

Additionnally, the sortData property can be used to define additionnal properties that will be added to the request only when the sort is active.

// ?sort=foo&type=bar
await refine.toggleSort('foo', {
	sortData: {
		type: 'bar',
	},
})

clearSorts

• Type: Function

Clears all active sorts.

currentSorts

• Type: Array<SortRefinement>

The list of currently active sorts.

currentFilters

• Type: Array<FilterRefinement>

The list of currently active filters.

getFilter

• Type: (name: string): FilterRefinement|undefined

Gets a filter object by name.

getSort

• Type: (name: string): SortRefinement|undefined

Gets a sort object by name.

reset

• Type: Function

Resets all filters and sorts.

The sorts array

This array contains an entry for each available sort.

Each entry extends SortRefinement and adds the toggle, isSorting and clear methods.

These methods are shorthands to toggleSort, isSorting and clearSort respectively, without the need for the sort name parameter.

The filters array

This array contains an entry for each available filter.

Each entry extends FilterRefinement and adds the apply and clear methods.

These methods are shorthands to applyFilter and clearFilter respectively, without the need for the filter name parameter.

Interfaces

The following are relevant interfaces used by useRefinements and its return value.

interface FilterRefinement {
	/**
	 * Whether this filter is currently active.
	 */
	is_active: boolean
	/**
	 * The type of this filter.
	 */
	type: 'trashed' | 'callback' | 'exact' | 'similar:loose' | 'similar:begins_with_strict' | 'similar:ends_with_strict' | string
	/**
	 * The label of the filter.
	 */
	label: string
	/**
	 * The metadata attributes of the filter.
	 */
	metadata: Record<string, any>
	/**
	 * The name of the fitler.
	 */
	name: string
	/**
	 * The current value of the filter.
	 */
	value: any
	/**
	 * Whether this filter is hidden.
	 */
	hidden: boolean
	/**
	 * The default value of the filter.
	 */
	default: any
}

interface SortRefinement {
	/**
	 * Whether this sort is currently active.
	 */
	is_active: boolean
	/**
	 * The current direction of the sort.
	 */
	direction?: SortDirection
	/**
	 * The default direction of the sort.
	 */
	default?: SortDirection
	/**
	 * The label of the sort.
	 */
	label: string
	/**
	 * The metadata attributes of the sort.
	 */
	metadata: Record<string, any>
	/**
	 * The name of the sort.
	 */
	name: string
	/**
	 * The value corresponding to the descending sort.
	 */
	desc: string
	/**
	 * The value corresponding to the ascending sort.
	 */
	asc: string
	/**
	 * The value that will be applied on toggle.
	 */
	next: string
	/**
	 * Whether this sort is hidden.
	 */
	hidden: boolean
}

interface Refinements {
	/**
	 * The list of available filters.
	 */
	filters: Array<FilterRefinement>
	/**
	 * The list of available sorts.
	 */
	sorts: Array<SortRefinement>
	/**
	 * The URL scope for these refinements.
	 */
	scope?: string
	/**
	 * The scope keys for these refinements.
	 */
	keys: {
		/**
		 * The scope key for sorting.
		 */
		sorts: string
		/**
		 * The scope key for filtering.
		 */
		filters: string
	}
}