Hybridly

Appearance

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.

RelatedRefining

Usage ​

ts
function useRefinements<
  Properties extends object,
  RefinementsKey extends keyof Properties
>(
  properties: Properties,
  refinementsKey: RefinementsKey,
  defaultOptions: HybridRequestOptions = {}
)
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 ​

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

const refine = useRefinements($props, 'refinements')
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.

toggleSort ​

  • Type: Function
  • Parameters: sortName: string

Toggles the specified sort. ToggleSortOptions is the same as HybridRequestOptions with an additional direction property, which should be 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.

clearFilter ​

  • Type: Function
  • Parameters: filter: string

Clears the specified filter.

clearFilters ​

  • Type: Function

Clears all active filters.

clearSorts ​

  • Type: Function

Clears all active sorts.

reset ​

  • Type: Function

Resets all filters and sorts.

isSorting ​

  • Type: ComputedRef<boolean>

Specifies whether there is an active sort.

isFiltering ​

  • Type: ComputedRef<boolean>

Specifies whether there is an active filter.

currentSorts ​

  • Type: Array<SortRefinement>

The list of currently active sorts.

currentFilters ​

  • Type: Array<FilterRefinement>

The list of currently active filters.

filters ​

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

sorts ​

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

getFilter ​

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

Gets a filter by name.

getSort ​

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

Gets a sort by name.

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.

Example

ts
const commercial = refine.bindFilter<bool>('commercial')
const search = refine.bindFilter<string>('search', {
	watch: (ref, cb) => watchDebounced(ref, cb, { debounce: 200 }),
})
const commercial = refine.bindFilter<bool>('commercial')
const search = refine.bindFilter<string>('search', {
	watch: (ref, cb) => watchDebounced(ref, cb, { debounce: 200 }),
})

Interfaces ​

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

ts
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
	}
}
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
	}
}