DoCmd.ApplyFilter method (Access)

Article
03/30/2022

The ApplyFilter method carries out the ApplyFilter action in Visual Basic.

Syntax

expression.ApplyFilter (FilterName, WhereCondition, ControlName)

expression A variable that represents a DoCmd object.

Parameters

Name	Required/Optional	Data type	Description
FilterName	Optional	Variant	A string expression that is the valid name of a filter or query in the current database. When using this method to apply a server filter, the FilterName argument must be blank.
WhereCondition	Optional	Variant	A string expression that is a valid SQL WHERE clause without the word WHERE.
ControlName	Optional	Variant

Remarks

Use the ApplyFilter action to apply a filter, a query, or an SQL WHERE clause to a table, form, or report to restrict or sort the records in the table or the records from the underlying table or query of the form or report. For reports, you can use this action only in a macro specified by the report's OnOpen event property.

Use this action to apply an SQL WHERE clause only when applying a server filter. A server filter cannot be applied to a stored procedure's record source.

Note

Use the FilterName argument if you've already defined a filter that provides the appropriate data. Use the WhereCondition argument to enter the restriction criteria directly. If you use both arguments, Microsoft Access applies the WHERE clause to the results of the filter. You must use one or both arguments.

You can apply a filter or query to a form in Form view or Datasheet view.

The filter and WHERE condition that you apply become the setting of the form's Filter property or the report's ServerFilter property.

When you save a table or form, Access saves any filter currently defined in that object, but will not apply the filter automatically the next time the object is opened (although it will automatically apply any sort that you applied to the object before it was saved).

If you want to apply a filter automatically when a form is first opened, specify a macro containing the ApplyFilter action or an event procedure containing the ApplyFilter method of the DoCmd object as the OnOpen event property setting of the form. You can also apply a filter by using the OpenForm or OpenReport action, or their corresponding methods. To apply a filter automatically when a table is first opened, you can open the table by using a macro containing the OpenTable action, followed immediately by the ApplyFilter action.

You must include at least one of the two ApplyFilter method arguments. If you enter a value for both arguments, the WhereCondition argument is applied to the filter.

The maximum length of the WhereCondition argument is 32,768 characters (unlike the WhereCondition action argument in the Macro window, whose maximum length is 256 characters).

Example

The following example uses the ApplyFilter method to display only records that contain the name "King" in the LastName field.

DoCmd.ApplyFilter , "LastName = 'King'"

The following example shows how to use the ApplyFilter property to filter the records displayed when a toggle button named tglFilter is chosen.

Private Sub tglFilter_Click()
    With tglFilter
        If .Value = True Then
            .Caption = "P/T"
            .StatusBarText = "only full-timers"
            DoCmd.ApplyFilter , "[Hours]=40"
        ElseIf .Value = False Then
            .Caption = "All"
            .StatusBarText = "only part-timers"
            DoCmd.ApplyFilter , "[Hours]<40"
        Else
            .Caption = "F/T"
            .StatusBarText = "all employees"
            DoCmd.ShowAllRecords
            .SetFocus 'to activate the button's statusbar-text
        End If
    End With
End Sub

Support and feedback

Have questions or feedback about Office VBA or this documentation? Please see Office VBA support and feedback for guidance about the ways you can receive support and provide feedback.

Share via